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XIElib - Function Group Introduction 


The following pages describe the format of the reference pages for each XIElib 
function. Every effort has been made to maintain consistency with the format 
used in Xlib Reference Manual for Version 11 (A. Nye, ed., O'Reilly & Associates, 
Inc., 1992). The reader is also referred to X Image Extension Protocol Reference 


Manual, Version 5.0 (R. Shelley, ed., 1994) for a complete definition of the XIE 
protocol. 


Name 
XieFunctionName - brief description of the function 
Syntax 


The Syntax section presents the calling syntax for the routine, including the 
declarations of the arguments and the return type. For example: 


returntype XieFunctionName (arg1, arg2_ret) 
typel arg1; 
type2 *arg2_ ret; 


Arguments 


The Arguments section describes each of the arguments used by the function. 
There are two sorts of arguments: arguments to specify data to the function and 
arguments that return data from the function. An example of each type follows: 


argl Specifies information for XieFunctionName. The 
description for this type of argument always starts with 
the word "Specifies." 

arg2_ret Returns information from XieFunctionName. The 
description for this type of argument always starts with 
the word "Returns." 


Returns 


This section is present when XieFunctionName returns a value and describes 
what is returned. 


Description 


The Description section describes what the function does, what it returns, and 
what events or side effects it causes. It also may contain pertinent definitions, 
algorithms, and tables. A description of each XIE event structure is presented in 
the section XIElib Events. 


Output Attributes 


This section, which presents a table of element output attributes, is present if 
XieFloFunctionName specifies an element that produces output data. 


Class Data class of output data 

- single band (achromatic or index) 

- triple band (trichromatic) 
Type Data type 

- constrained (quantization levels is Levels) 

- unconstrained (quantization levels is unknown) 
Width Width of output (in pixels per band) 


Height Height of output (in pixels per band) 

Levels Depends on type 
- constrained: number of quantization levels 
- unconstrained: unknown 


Structures 


The Structures section contains the C definitions of the XIE-specific data types 
used by XieFunctionName as arguments or return values. It also contains 
definitions of important constants used by the function. 


Errors 


The Errors section is present when an action of XieFunctionName could 
generate an error. A table of errors that can be generated and their causes is 
presented. The full list of errors is presented in the section XIElib Errors. 


See Also 


This section lists other functions that contain information related to 
XieFunctionName. 


XIElib - Startup Functions XielInitialize 


Name 
XielInitialize - initialize the XIE extension 
Syntax 


Status XieInitialize (display, extinfo_ret) 
Display *display; 
XieExtensionInfo **extinfo_ret; 


Arguments 
display Specifies a connection to an X server. 
extinfo_ret Returns the pointer to an XieExtensionInfo structure, 
which contains information about the XIE server's 
capabilities. 
Returns 


Zero on failure, nonzero on success. 
Description 


Xielnitialize initializes the interface to the XIE extension and returns information 
about the XIE server's capabilities. XieInitialize should be called to establish 
version compatibility between client and server prior to making any other XIE 
request. 


If successful, XieInitialize allocates and fills the XieExtensionInfo structure as 
follows: 


The server major rev and server minor rev members are set to specify the 
highest version of the XIE protocol that the server supports. If the server 
version is higher than the XIElib version, the server will return the lower 
version, if it supports it. 

The service class member is set to the service-class supported by the XIE 
server. Service-class defines the recognized image-processing service sets 
supported by the X Image Extension standard; the two service classes 
currently defined are Full, the entire XIE protocol, and DIS, the Document 
Image Subset, a proper subset of Full XIE. The service class member can be 
set to one of the standard values: 


xieValFull 
xieValDIS 


The alignment member is set to the pixel and scanline alignment for image 
data supported by the server. Values for this member can be either 
xieValAlignable or xieValArbitrary. xieValAlignable data units must fit evenly 
within a byte, or they must fill a byte, or fill a multiple of bytes; 
xieValArbitrary data units may fall at any bit address. 

The uncnst mantissa member is set to the number of bits in the server’s 
floating-point format (including the sign bit). If the server uses fixed point, 
uncnst_mantissa is set to zero. 

The uncnst_min exp member is set to the smallest (most negative) value n 
such that 2n is representable in the server’s unconstrained data format. 


The uncnst_max exp member is set to the largest value n such that 2n - 1 is 
representable in the server’s unconstrained data format. 

The n_cnst_levels member is the number of items in the list cnst_levels. 

The items in the list cnst_levels are set to the levels that are “recommended” 
for constrained data by the server. A value of zero means 232 levels. 

The first_event member is set to the value from which subsequent XIE events 
values are based. 

The first_error member is set to the value from which subsequent XIE error 
values are based. 


The memory allocated to extinfo_ret is freed when display is closed via 
XCloseDisplay; the client should not free this memory. 


If not successful, XieInitialize sets **extinfo_ ret to NULL. 


Structures 


typedef struct { 
unsigned server_major rev; 
unsigned server minor rev; 
XieServiceClass service class; 
XieAlignment alignment; 
int uncnst_mantissa; 
int uncnst_min exp; 
int uncnst_ max exp; 
int n_cnst levels; 
unsigned long *cnst_levels; 
int major_ opcode; 
int first event; 
int first_error; 

} XieExtensionInfo; 


/* Definitions of Extension Name and Version Number */ 
#define xieMajorVersion 

#define xieMinorVersion 0 
#define xieEarliestMinorVersion 0 
#define xieLatestMinorVersion 0 


ol 


/* Definitions of ServiceClass */ 


#define xieValFull 1 
#define xieValDIS 2 
/* Definitions of Alignment */ 

#define xieValAlignable 1 


#define xieValArbitrary 2 


XIElib - Startup Functions XieQueryTechniques 


Name 


XieQueryTechniques - return information about the standard and private 
techniques that are supported by the server 


Syntax 


Status XieQueryTechniques (display, technique_group, ntechniques ret, 
techniques ret) 
Display *display; 
XieTechniqueGroup technique_group; 
int *ntechniques ret; 
XieTechnique **techniques ret; 


Arguments 
display Specifies a connection to an X server. 
technique_group Specifies the group of techniques for which the server is 
to return information. 
ntechniques ret Returns the number of items in the list of XieTechnique 
structures. 
techniques ret Returns the pointer to the list of XieTechnique 
structures, which contains the information about the 
selected group of techniques. 
Returns 


Zero on failure, nonzero on success. 
Description 


If successful, XieQueryTechniques allocates and fills each XieTechnique 
structure in the list as follows: 


The member needs param is set to True if the technique requires additional 
parameters; needs param is set to False if the technique takes no 
parameters, or it has parameters that are optional. If parameters are 
optional, they must be totally omitted, or they must all be supplied. 

The member group is set to the group the technique belongs to. 

The member number is set to the numeric identifier assigned to the 
technique. 

The member speed is set to the server's assessment of the speed of this 
technique relative to other techniques in the same group, where 0 is slowest 
and 255 is fastest. 

The member name is set to the XIE compliant technique name string. 


To free the memory allocated to techniques ret, use XieFreeTechniques. 
On failure, ntechniques ret is set to zero and *techniques ret is set to NULL. 


The standard technique group names that can be queried using 
XieQueryTechniques are: 


Technique group | Meaning Cid 
xieValDefault Select all default techniques 


xieValAll Select all supported techniques 
xieValColorAlloc Select color allocation techniques 
xieValConstrain Select techniques for constraining data 


xieValConvertFromRGB Select colorspace conversion techniques (for 
conversion from the RGB colorspace) 

xieValConvertToRGB Select colorspace conversion techniques (for 
conversion to the RGB colorspace) 


xieValDecode Select image decoding (decompression) 
techniques 


techniques 
compression techniques 


xieValWhiteAdjust Select colorspace conversion white point 
adjustment techniques 


If a vendor defined an additional private technique group, it could be discovered 
by querying for all groups. 


xieValConvolve Select techniques for handling convolution 
edge conditions 


Structures 


typedef unsigned XieTechniqueGroup; 
typedef struct { 
Bool needs param; 
XieTechniqueGroup group; 
unsigned int number; 
unsigned int speed; 
char *name; 
} XieTechnique; 


/* Definitions for TechniqueGroups */ 

#define xieValDefault 0 
#define xieValAll 1 
#define xieValColorAlloc 2 
#define xieValConstrain 4 
#define xieValConvertFromRGB 6 
#define xieValConvertToRGB 8 


#define xieValConvolve 10 
#define xieValDecode 12 
#define xieValDither 14 
#define xieValEncode 16 
#define xieValGamut 18 
#define xieValGeometry 20 
#define xieValHistogram 22 
#define xieValWhiteAdjust 24 
Errors 


BadAlloc Insufficient resources 


BadValue Unknown technique_group 


See Also 


XieFreeTechniques 


XIElib - Color List Functions XieCreateColorList 


Name 
XieCreateColorList - create a color list 
Syntax 


XieColorList XieCreateColorList (display) 
Display *display; 


Arguments 
display Specifies a connection to an X server. 
Returns 


The color list identifier. 
Description 


XieCreateColorList creates a color list resource and returns its color list ID. 


The color list created is an unpopulated server resource that can be used to 
store the list of colors allocated by XieFloConvertToIndex. The Colormap 
allocations that are recorded in a color list belong to the client that executed the 
photoflo that populated the resource (this is not necessarily the same client that 
created the color list). A color list cannot be the target of more than one active 
photoflo at a time. The contents of a color list may be queried using 
XieQueryColorList. All allocated cells can be explicitly purged from a color list 
using XiePurgeColorList. A color list can be destroyed using 
XieDestroyColorList. 


Structures 
typedef XID XieColorList; 


Errors 
BadAlloc Insufficient resources 
BadIdChoice Invalid color list 

See Also 


XieDestroyColorList, XiePurgeColorList, XieQueryColorList, 
XieFloConvertToIndex 


XIElib - Color List Functions XieDestroyColorList 


Name 
XieDestroyColorList - destroy a color list 
Syntax 


void XieDestroyColorList (display, color list) 
Display *display; 
XieColorList color list; 


Arguments 
display Specifies a connection to an X server. 
color list Specifies the color list to be destroyed. 
Description 


XieDestroyColorList destroys the color list resource identified by color list. Once 
destroyed, color list ID is no longer valid. 


Structures 

typedef XID XieColorList; 
Errors 

xieErrNoColorlist Invalid color list 
See Also 

XieCreateColorList 


XIElib - Color List Functions XiePurgeColorList 


Name 
XiePurgeColorList - purge all allocated cells from a color list 
Syntax 


void XiePurgeColorList (display, color list) 
Display *display; 
XieColorList color list; 


Arguments 
display Specifies a connection to an X server. 
color list Specifies the color list to be purged. 
Description 


XiePurgeColorList frees the colors from the specified color list. 


Structures 
typedef XID XieColorList; 


Errors 
BadAccess Attempt to purge colors when color list is being written 
by a photoflo 
xieErrNoColorlist Invalid color _list 
See Also 


XieCreateColorList, XieDestroyColorList, XieQueryColorList, 
XieFloConvertToIndex 


XIElib - Color List Functions XieQueryColorList 


Name 


XieQueryColorList - obtain a list of allocated Colormap indices 


Syntax 


Status XieQueryColorList (display, color list, colormap ret, ncolors ret, 
colors ret) 
Display *display; 
XieColorList color list; 
Colormap *colormap ret; 
unsigned *ncolors ret; 
unsigned long **colors ret; 


Arguments 
display Specifies a connection to an X server. 
color list Specifies the color list to query. 
colormap ret Returns the Colormap from which the colors were 
allocated. 
ncolors_ret Returns the number of Colormap indices in the list. 
colors ret Returns the list of allocated Colormap indices. 
Returns 


Zero on failure, nonzero on success. 


Description 


XieQueryColorList allocates and returns a list of colors allocated by a 
ConvertToIndex element. 


When there are no colors in color list, a zero status is returned, the value zero is 
returned for the colormap, and the list of colors is of length zero. The pointer to 
the list of allocated Colormap indices is set to NULL. 


To free the memory allocated to colors ret, use XFree. 
Structures 

typedef XID XieColorList; 
Errors 


BadAlloc Insufficient resources 
xieErrNoColorlist Invalid color list 


See Also 


XieCreateColorList, XieDestroyColorList, XieQueryColorList, 
XieFloConvertToIndex 


XIElib - LUT Functions XieCreateLUT 


Name 
XieCreateLUT - create a lookup table 
Syntax 


XieLut XieCreateLUT (display) 
Display *display; 


Arguments 

display Specifies a connection to an X server. 
Returns 

The lookup table (LUT) identifier. 
Description 


XieCreateLUT creates a server resource that is used as a lookup table (LUT) by 
a Point element. A lookup table consists of one or three single-dimension arrays, 
each long enough to contain an entry for all possible pixels values in the image 
data to which the Point element will be applied. 


The LUT is populated (or repopulated) with lookup table entries after the 
successful execution of a photoflo containing an ExportLUT element that targets 
lut. LUT data can be imported into a photoflo using an ImportLUT element. 


Structures 
typedef XID XieLut; 
Errors 


BadAlloc Insufficient resources 
BadIDChoice Invalid LUT 


See Also 
XieDestroyLUT, XieFloImportLUT, XieFloExportLUT 


XIElib - LUT Functions XieDestroyLUT 


Name 
XieDestroyLUT - destroy a lookup table 
Syntax 


void XieDestroyLUT (display, lut) 
Display *display; 
XieLut lut; 


Arguments 


display Specifies a connection to an X server. 
lut Specifies the ID of the LUT to be destroyed. 


Description 


XieDestroyLUT destroys the lookup table (LUT) identified by Jut. Once destroyed, 
LUT ID is no longer valid. 


Structures 
typedef XID XieLut; 


Errors 
xieErrNoLut The value for the /ut argument does not name a defined 
LUT 
See Also 


XieDestroyLUT, XieFloImportLUT, XieFloExportLUT 


XIElib - Photomap Functions XieCreatePhotomap 


Name 
XieCreatePhotomap - create a photomap 
Syntax 


XiePhotomap XieCreatePhotomap (display) 
Display *display; 


Arguments 

display Specifies a connection to an X server. 
Returns 

The photomap identifier. 
Description 


XieCreatePhotomap creates a photomap, a server resource that stores image 
data. Photomap data may be rendered for display or used as input to control or 
modify the rendition of another image. 


Photomap attributes are defined when a photoflo containing an ExportPhotomap 
element populates the photomap with data. 

Structures 
typedef XID XiePhotomap; 


Errors 
BadAlloc Insufficient resources 
BadIdChoice Invalid photomap 
See Also 


XieDestroyPhotomap, XieQueryPhotomap, XieFloImportPhotomap, 
XieFIloExportPhotomap 


XIElib - Photomap Functions XieDestroyPhotomap 


Name 
XieDestroyPhotomap - destroy a photomap 
Syntax 


void XieDestroyPhotomap (display, photomap) 
Display *display; 
XiePhotomap photomap; 


Arguments 

display Specifies a connection to an X server. 

photomap Specifies the ID of the photomap to be destroyed. 
Description 


XieDestroyPhotomap destroys the photomap identified by photomap. Once 
destroyed, the photomap ID is no longer valid. A photomap is the XIE resource 
used to store image data in the server. 


Structures 
typedef XID XiePhotomap; 
Errors 
xieErrNoPhotomap The value for the photomap argument does not name a 
defined photomap 
See Also 


XieCreatePhotomap , XieQueryPhotomap, XieFloImportPhotomap, 
XieFIloExportPhotomap 


XIElib - Photomap Functions XieQueryPhotomap 


Name 


XieQueryPhotomap - return the queriable attributes of a photomap 
Syntax 


Status XieQueryPhotomap (display, photomap, populated _ret, datatype ret, 
class_ret, decode technique ret, width_ret, height_ret, levels ret) 
Display *display; 
XiePhotomap photomap; 
Bool *populated _ret; 
XieDataType *datatype ret; 
XieDataClass *class_ ret; 
XieDecodeTechnique *decode technique ret; 
XieLTriplet width_ret; 
XieLTriplet height ret; 
XieLTriplet levels ret; 


Arguments 

display Specifies a connection to an X server. 

photomap Specifies the photomap to be queried. 

populated ret Returns the status of the photomap. 

datatype_ret Returns the type of data in the photomap. 

class_ret Returns the class of data in the photomap. 

decode technique ret Returns the decode technique required to interpret the 

data. 

width_ret Returns the width, in pixels per band. 

height_ret Returns the height, in pixels per band. 

levels ret Returns the number of quantization levels per band. 
Returns 


Zero on failure, nonzero on success. 
Description 


A photomap is a server resource that stores image data. XieQueryPhotomap sets 
populated ret to indicate whether or not photomap has been populated with 
attributes and data. If populated _ret is False, all remaining fields contain zeros. 


datatype_ret reports whether the photomap contains constrained or 
unconstrained data, and is set to one of the following standard data type values: 


xieValConstrained 
xieValUnconstrained 


class_retis the class of image data (that is, single-band or triple-band) and is set 
to one of the following standard data class values: 


xieValSingleBand 
xieValTripleBand 


width_ret and height_ret are set to the dimensions of the image data in pixels 
(per band). levels ret is set to the potential dynamic range, or number of 


quantization levels (per band). If datatype_ret is set to unconstrained, the 
returned values for levels are zeros. If class_ret is xieValSingleBand, width_ret, 
height_ret, and levels _ret are only valid for element 0 in each of these vectors; 
elements 1 and 2 are unused and are returned as zeros. 


decode technique ret is set to the decode technique that will be required to 
interpret or decompress the data. Decode techniques define the techniques that 
can be used to interpret uncompressed image data or decode compressed 
images. decode _ technique ret can be set to one of the following standard decode 
technique values: 


xieValDecodeUncompressedSingle 
xieValDecodeUncompressedTriple 
xieValDecodeG31D 
xieValDecodeG32D 
xieValDecodeG42D 
xieValDecodeJPEGBaseline 
xieValDecodeJPEGLossless 
xieValDecodeTIFF2 
xieValDecodeTIFFPackBits 


If a vendor defined additional private decode techniques, decode_technique_ret 
can be set to the values given to these techniques. 


Structures 


typedef unsigned XieDataClass; 
typedef unsigned XieDataType; 
typedef unsigned XieDecodeTechnique; 
typedef unsigned long XieLTriplet[3]; 
typedef XID XiePhotomap; 


/* Definitions of DataType */ 


#define xieValConstrained 1 
#define xieValUnconstrained 2 
/* Definitions of DataClass */ 
#define xieValSingleBand 1 
#define xieValTripleBand 2 
/* Definitions for DecodeTechniques */ 
#define xieValDecodeUncompressedSingle 2 
#define xieValDecodeUncompressedTriple 3 
#define xieValDecodeG31D 4 
#define xieValDecodeG32D 6 
#define xieValDecodeG42D 8 
#define xieValDecodeJPEGBaseline 10 
#define xieValDecodeJPEGLossless 12 
#define xieValDecodeTIFF2 14 
#define xieValDecodeTIFFPackBits 16 
Errors 
xieErrNoPhotomap The value for the photomap argument does not name a 
defined photomap. 


xieErrNoFloAlloc Insufficient resources (for exmple, memory) 


XIElib - ROI Functions XieCreateROI 


Name 
XieCreateROI - create a Rectangles-Of-Interest 
Syntax 


XieRoi XieCreateROI (display) 
Display *display; 


Arguments 

display Specifies a connection to an X server. 
Returns 

The ROI (Rectangles-Of-Interest) identifier. 
Description 


XieCreateROI creates a server ROI (Rectangles-Of-Interest) resource, and 
returns its resource ID to the client. 


Structures 
typedef XID XieRoi; 
Errors 


BadAlloc Insufficient resources 
BadIDChoice Invalid ROI 


See Also 
XieDestroyROI, XieFloImportROI, XieFloExportROI 


XIElib - ROI Functions XieDestroyROI 


Name 
XieDestroyROI - destroy a Rectangles-Of- Interest 
Syntax 


void XieDestroyROI (display, roi) 
Display *display; 


XieRoi roi; 
Arguments 
display Specifies a connection to an X server. 
roi Specifies the ID of the ROI to be destroyed. 
Description 


XieDestroyROI destroys the Rectangles-Of-Interest (ROI) identified by roi. Once 
destroyed, roi is no longer valid. 


Structures 
typedef XID XieRoi; 


Errors 
xieErrNoROI The value for the roi argument does not name a defined 
ROI 
See Also 


XieCreateROI 


XIElib - Immediate Photoflo Functions XieCreatePhotospace 


Name 
XieCreatePhotospace - create a photospace 
Syntax 


XiePhotospace XieCreatePhotospace (display) 
Display *display; 


Arguments 

display Specifies a connection to an X server. 
Returns 

The photospace identifier. 
Description 


XieCreatePhotospace returns a resource-id for a new photospace that can be 
used to accommodate immediate photoflos instantiated by a client. Any client 
that needs to instantiate immediate photoflos must create at least one 
photospace. 


Structures 
typedef XID XiePhotospace; 


Errors 
BadAlloc Insufficient resources 
BadIDChoice Invalid photospace 
See Also 


XieDestroyPhotospace, XieExecuteImmediate 


XIElib - Immediate Photoflo Functions XieDestroyPhotospace 


Name 
XieDestroyPhotospace - destroy a photospace 
Syntax 


void XieDestroyPhotospace (display, photospace) 
Display *display; 
XiePhotospace photospace; 


Arguments 

display Specifies a connection to an X server. 

photospace Specifies the ID of the photospace to be destroyed. 
Description 


XieDestroyPhotospace destroys a photospace. Prior to destroying the 
photospace, all photoflos that are currently active in the photospace will be 
aborted, exported data pending client retrieval will be freed, and the photoflos 
will be destroyed. 


Structures 
typedef XID XiePhotospace; 
Errors 


xieErrNoPhotospace The value for the photospace argument does not name 
a defined photospace 


See Also 


XieCreatePhotospace 


XIElib - Immediate Photoflo Functions XieExecuteImmediate 


Name 


XieExecuteImmediate - define and begin execution of an immediate photoflo 
Syntax 


void XieExecuteImmediate (display, photospace, flo id, notify, elem list, 
elem_count) 
Display *display; 
XiePhotospace photospace; 
unsigned long flo id; 
Bool notify; 
XiePhotoElement *elem list; 
int elem_ count; 


Arguments 
display Specifies a connection to an X server. 
photospace Specifies the ID of the photospace to be executed. 
flo_id Specifies a particular instance of the photoflo to be 
executed. 
notify Specifies whether a PhotofloDone event must be sent 
upon completion. 
elem list Specifies the import, process, and export elements to be 
executed. 
elem_count Specifies the number of items in elem list. 
Description 


XieExecuteImmediate begins the asynchronous execution of an immediate 
photoflo. The server does not save a copy of an immediate photoflo after the 
photoflo has completed execution and all data exported for the client have been 
retrieved. An immediate photoflo may therefore not be modified or totally 
redefined prior to subsequent executions. It is legal to have multiple unique 
instances of immediate photoflos (and stored photoflos) active concurrently. 


The photospace/flo id argument pair specifies the instance by which this 
photoflo will be identified in other requests, events, or errors. notify specifies 
whether a PhotofloDone event must be sent upon completion. The PhotofloDone 
event notifies the client that a photoflo has left the active state: it is no longer 
executing. elem _ list defines the import, process, and export elements to be 
executed. 


If any clients have blocked themselves during the execution of the photoflo (see 
XieAwait), they will become unblocked when the photoflo's state changes from 
active to nonexistent. 


Care should be taken that the argument pair elem list/elem_count matches a 
returned value (an array of XiePhotoElement structures) and argument count 
from a call to XieAllocatePhotofloGraph. 


Structures 
typedef XID XiePhotospace; 
typedef struct { 


int elemType; 
/* union of ALL element types */ 


union { 
} data; 
} XiePhotoElement; 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloElement Invalid element type(s) in elem list 
xieErrNoFloID Invalid photospace/flo id argument pair has been 
specified 
xieErrNoFlo An error has been detected while defining, executing, or 
accessing a photoflo (See Photoflo Errors). 
See Also 


XieAwait, XieAllocatePhotofloGraph 


XIElib - Photoflo Functions XieAllocatePhotofloGraph 


Name 
XieAllocatePhotofloGraph - allocate an array of XiePhotoElement structures 
Syntax 


XiePhotoElement *XieAllocatePhotofloGraph (count); 
unsigned int count; 


Arguments 
count Specifies the number of XiePhotoElement structures to 
allocate. 
Returns 


The array of XiePhotoElement structures. 


Description 


XieAllocatePhotofloGraph allocates and returns a pointer to an array of 
XiePhotoElement structures; each field of each structure in the array is set to 
zero (0). 


To free the memory allocated to the list of XiePhotoElement structures, use 
XieFreePhotofloGraph . 


If XieAllocatePhotofloGraph is unable to create an XiePhotoElement array , it 
returns NULL. 


Structures 


typedef struct { 
int elemType; 
/* union of ALL element types */ 
union { 


} data; 
} XiePhotoElement; 


See Also 


XieFreePhotofloGraph, XieCreatePhotoflo, XieModifyPhotoflo, 
XieRedefinePhotoflo, XieExecutePhotoflo, XieExecuteImmediate 


XIElib - Stored Photoflo Functions XieCreatePhotoflo 


Name 
XieCreatePhotoflo - create a stored photoflo 
Syntax 


XiePhotoflo XieCreatePhotoflo (display, elem list, elem_count) 
Display *display; 
XiePhotoElement *elem list; 
int elem_count; 


Arguments 
display Specifies a connection to an X server. 
elem list Specifies the defining array of XiePhotoElement 
structures. 
elem_ count Specifies the number of XiePhotoElement structures in 
the array. 
Returns 


The photoflo identifier. 
Description 


XieCreatePhotoflo creates a stored photoflo resource, defines its complete 
contents using the contents of elem list, sets it in the inactive state, and returns 
its resource-id. Stored photoflos persist beyond execution and may be modified 
or totally redefined prior to subsequent executions. 


The returned photoflo identifier is a new resource-id that, along with the 
execution domain used for the photoflo, identifies this photoflo in other requests, 
events, or errors. elem list defines the import, process, and export elements to 
be stored for execution. Although resources and parameters are specified at 
creation, no action is taken to validate them at that time. XieCreatePhotoflo will 
only store the photoflo's definition: parameter validation is delayed until an 
execute request is received. 


Structures 
typedef XID XiePhotoflo; 


typedef struct { 
int elemType; 
/* union of ALL element types */ 
union { 


} data; 
} XiePhotoElement; 


Errors 


BadAlloc Insufficient resources 

BadIdChoice Invalid photoflo 

xieErrNoFloAlloc Insufficient resources (for example, memory) for 
elem list 


xieErrNoFloElement Invalid element type(s) in elem list 
xieErrNoFlo An error has been detected while defining, executing, or 
accessing a photoflo (see Photoflo Errors). 


See Also 


XieAllocatePhotofloGraph, XieFreePhotofloGraph, XieModifyPhotoflo, 
XieRedefinePhotoflo, XieExecutePhotoflo, XieQueryPhotoflo, XieDestroyPhotoflo 


XIElib - Stored Photoflo Functions XieDestroyPhotoflo 


Name 
XieDestroyPhotoflo - destroy a stored photoflo 
Syntax 


void XieDestroyPhotoflo (display, photoflo) 
Display *display; 
XiePhotoflo photoflo; 


Arguments 
display Specifies a connection to an X server. 
photoflo Specifies the photoflo to be destroyed. 
Description 


XieDestroyPhotoflo destroys a stored photoflo. If photoflo is active, that is, 
executing, it is aborted and all exported data that are pending client retrieval 
are freed prior to destroying photoflo. 


Structures 
typedef XID XiePhotoflo; 
Errors 
xieErrNoPhotoflo The value for the photoflo argument does not name a 
defined photoflo 
See Also 


XieCreatePhotoflo 


XIElib - Stored Photoflo Functions XieExecutePhotoflo 


Name 
XieExecutePhotoflo - execute a stored photoflo 
Syntax 


void XieExecutePhotoflo (display, photoflo, notify) 
Display *display; 
XiePhotoflo photoflo; 


Bool notify; 
Arguments 
display Specifies a connection to an X server. 
photoflo Specifies the photoflo to be executed. 
notify Specifies that a PhotofloDone event must be sent upon 
completion. 
Description 


XieExecutePhotoflo changes a stored photoflo to the active state. Execution is 
asynchronous. The photoflo returns to the inactive state when execution 
completes and all data exported for the client have been retrieved. It is legal to 
have multiple stored photoflos (and immediate photoflos) active concurrently. 


notify specifies that a PhotofloDone event must be sent upon completion. A 


PhotofloDone event notifies the client that a photoflo has left the active state (it 
is no longer executing). 


Stored photoflos persist beyond execution and may be modified or totally 
redefined prior to subsequent executions. 

Structures 
typedef XID XiePhotoflo; 


Errors 
xieErrNoPhotoflo The value for the photoflo argument does not name a 
defined photoflo 
xieErrNoFloAccess Attempt to execute photoflo when it is already active 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFlo An error has been detected while defining, executing, or 
accessing a photoflo (see Photoflo Errors). 
See Also 


XieCreatePhotoflo, XieModifyPhotoflo, XieRedefinePhotoflo, XieQueryPhotoflo, 
XieDestroyPhotoflo, XieAbort, XieAwait, XieGetClientData, XiePutClientData 


XIElib - Stored Photoflo Functions XieModifyPhotoflo 


Name 
XieModifyPhotoflo - modify a stored photoflo 


Syntax 


void XieModifyPhotoflo (display, photoflo, start, elem _ list, elem_count) 
Display *display; 
XiePhotoflo photoflo; 
int start; 
XiePhotoElement *elem list; 
int elem_count; 


Arguments 
display Specifies a connection to an X server. 
photoflo Specifies the photoflo to be modified. 
start Specifies the index where element replacement is to 
begin. 
elem list Specifies an array of elements that will replace existing 
elements. 
elem_ count Specifies the number of items in elem list. 
Description 


XieModifyPhotoflo allows element parameters of a stored photoflo to be 
modified. Stored photoflos persist beyond execution and may be modified prior 
to subsequent executions. 


start is the position or index of an element within an array of elements used to 
specify a photoflo; the first element in the array has a start value of one (1). 


XieModifyPhotoflo only allows parameter modification. No topological changes 
are allowed: elements cannot be deleted, inserted, or appended. 
Structures 
typedef XID XiePhotoflo; 
typedef struct { 
int elemType; 


/* union of ALL element types */ 
union { 


} data; 
} XiePhotoElement; 


Errors 


xieErrNoPhotoflo The value for the photoflo argument does not name a 
defined photoflo 
xieErrNoFloAccess Attempt to change photoflo when it is already active 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloElement Invalid element type(s) in elem list or 
attempt to append additional element(s) to photoflo 
xieErrNoFloSource An invalid start has been specified or 
attempt to change input connections of type 
XiePhototag in elem list 
xieErrNoFlo An error has been detected while defining, executing, or 
accessing a photoflo (see Photoflo Errors). 


See Also 


XieAllocatePhotofloGraph, XieFreePhotofloGraph, XieCreatePhotoflo, 
XieRedefinePhotoflo, XieExecutePhotoflo, XieQueryPhotoflo, XieDestroyPhotoflo 


XIElib - Stored Photoflo Functions XieRedefinePhotoflo 


Name 
XieRedefinePhotoflo - redefine a stored photoflo 
Syntax 


void XieRedefinePhotoflo (display, photoflo, elem list, elem count) 
Display *display; 
XiePhotoflo photoflo; 
XiePhotoElement *elem list; 
int elem count; 


Arguments 
display Specifies a connection to an X server. 
photoflo Specifies the photoflo to be redefined. 
elem list Specifies an array of elements that will replace all 
existing elements. 
elem count Specifies the number of items in elem list. 
Description 


XieRedefinePhotoflo allows all elements of a stored photoflo to be removed and 

replaced with a new list. Stored photoflos persist beyond execution and may be 

totally redefined prior to subsequent executions. 

There are no restrictions on changing element types or the array's size. 
Structures 

typedef XID XiePhotoflo; 

typedef struct { 


int elemType; 
/* union of ALL element types */ 


union { 
} data; 
} XiePhotoElement; 
Errors 
xieErrNoPhotoflo The value for the photoflo argument does not name a 
defined photoflo 
xieErrNoFloAccess Attempt to change photoflo when it is already active 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloElement Invalid element type(s) in elem list 
xieErrNoFlo An error has been detected while defining, executing, or 


accessing a photoflo (see Photoflo Errors). 


See Also 


XieAllocatePhotofloGraph, XieFreePhotofloGraph, XieCreatePhotoflo, 
XieModifyPhotoflo, XieExecutePhotoflo, XieQueryPhotoflo, XieDestroyPhotoflo 


XIElib - Photoflo Functions XieQueryPhotoflo 


Name 


XieQueryPhotoflo - return the current status of a photoflo 


Syntax 


XieQueryPhotoflo(display, name _ space, flo id, state _ret, data expected ret, 
nexpected ret, data available ret, navailable ret) 
Display *display; 
unsigned long name_space; 
unsigned long flo id; 
XiePhotofloState *state_ret; 
XiePhototag **data expected ret; 
unsigned int *nexpected_ret; 
XiePhototag **data_ available ret; 
unsigned int *navailable ret; 


Arguments 
display Specifies a connection to an X server. 
name_space Specifies the execution domain used for the photoflo to 
query. 
flo_id Specifies a particular instance of the photoflo to query. 
state_ret Returns the state of the photoflo. 
data expected ret Returns a list of ImportClient elements. 
nexpected_ret Returns the length of data_expected_ret. 
data _ available ret Returns a list of ExportClient elements. 
navailable ret Returns the length of data_available ret. 
Returns 


Zero on failure, nonzero on success. 


Description 


XieQueryPhotoflo will return the current status of a photoflo. 


The name _space/flo id argument pair specifies the instance that identifies the 
photoflo that is being queried. state_ret indicates the state of the photoflo, and if 
XieQueryPhotoflo is successful, will return one of the following standard photoflo 
state values: 


xieValInactive 
xieValActive 
xieValNonexistent 


data expected ret is a list of ImportClient elements that are expecting data via 
XiePutClientData. data available ret is a list of ExportClient elements from 
which data are available (via XieGetClientData). Either or both of these lists may 
be of length zero, indicated by the returned values of nexpected_ret and 
navailable ret. 


XieQueryPhotoflo allocates memory for the list of ImportClient elements and the 
list of ExportClient elements. To free the memory allocated to data expected _ret 
and data_available ret, use XFree. 


Specifying an unknown or invalid instance will return a state _ret of nonexistent 
and zero length data_expected_ret and data available ret lists. 


Structures 
typedef unsigned XiePhotofloState; 


/* Definitions of PhotofloState */ 
#define xieValInactive 

#define xieValActive 

#define xieValNonexistent 


WNFR 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 


See Also 


XieCreatePhotoflo, XieModifyPhotoflo, XieRedefinePhotoflo, XieExecutePhotoflo, 
XieDestroyPhotoflo, XieGetClientData, XiePutClientData 


XIElib - Client Data Functions XiePutClientData 


Name 
XiePutClientData - send a stream of data to an active photoflo 
Syntax 


void XiePutClientData (display, name_ space, flo id, element, final, band_number, 

data, nbytes) 

Display *display; 

unsigned long name_space; 

unsigned long flo id; 

XiePhototag element; 

Bool final; 

unsigned band_number; 

unsigned char *data; 

unsigned nbytes; 


Arguments 
display Specifies a connection to an X server. 
name space Specifies the execution domain used for the photoflo to 
receive the data. 
flo_id Specifies a particular instance of the photoflo to receive 
the data. 
element Specifies the element to receive the data. 
final Specifies if the data is the last segment of data to be 
sent. If True, then data represents the last data to be 
sent by the client. False indicates that more data will be 
sent (during a subsequent call to XiePutClientData). 
band_number Specifies which band of data is being sent. 
data Specifies a counted list of bytes that comprises the data 
stream. 
nbytes Specifies the count of bytes that comprises the data 
stream. 
Description 


XiePutClientData sends a stream of data to an active photoflo. Since the 
complete data object may be larger than can fit in a single protocol request, XIE 
allows the stream to be segmented; the last segment is signaled with a final flag. 


The organization and contents of the data stream must match the parameters 
given to the ImportClient element or the results are undefined. An arbitrary 
amount of image data can be sent per request, whereas for nonimage data one 
or more complete aggregates must be sent per request (for example, one or 
more LUT array entries). If too many data are sent (for example, too many 
rectangles, or too many scanlines), the unwanted data are discarded. It is an 
error, however, to send too few data prior to signaling final. 


For stored photoflos, name_space is always ServerIDSpace (the value zero) and 
flo_id is the photoflo's resource-id. For immediate photoflos name_space is a 


photospace resource-id and flo id is 32-bit value that uniquely identifies the 
instance of the photoflo within name _space. 


Structures 
typedef unsigned XiePhototag; 


Errors 
xieErrNoFloAccess Executable photospace/flo_ id argument pair not active 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloElement Invalid element type specified by element 
xieErrNoFloID Invalid photospace/flo id argument pair has been 
specified 
xieErrNoFloValue Invalid band_number or 
for nonimage data, data contains a partial aggregate 
See Also 


XieGetClientData, XieQueryPhotoflo, XieFloImportClientPhoto, 
XieFloImportClientROL, XieFloImportClientLUT 


XIElib - Client Data Functions XieGetClientData 


Name 


XieGetClientData - retrieve data from an ExportClient element within an active 


Syntax 


photoflo 


Status XieGetClientData (display, name_space, flo id, element, max_bytes, 


terminate, band number, new state ret, data_ret, nbytes ret) 
Display *display; 


unsigned long name_space; 


unsigned long flo id; 


XiePhototag element; 


unsigned max_bytes; 
Bool terminate; 


unsigned band_number; 
XieExportState *new state _ret; 
unsigned char **data ret; 
unsigned *nbytes ret; 


Arguments 


display 
name_ space 


flo_id 


element 
max_ bytes 


terminate 


band_number 
new_state_ret 


data ret 


nbytes ret 


Returns 


Specifies a connection to an X server. 

Specifies the execution domain used for the photoflo 
from which to retrieve data. 

Specifies a particular instance of the photoflo from 
which to retrieve data. 

Specifies the element from which to retrieve the data. 
Specifies the maximum number of bytes that can be 
sent to the client. 

Specifies whether more data are wanted after this 
request. 

Specifies which band of data is being retrieved. 
Returns the status of the ExportClient element after this 
request. 

Returns a counted list of bytes that comprises the data 
stream. 

Returns the count of bytes that comprises the data 
stream. 


Zero on failure, nonzero on success. 


Description 


XieGetClientData returns data in a contiguous read-once byte stream, which can 
be requested in segments that are limited in size by the amount the client 
desires or the amount of data available from the server. The format of the data 
depends on the parameters given to the ExportClient element from which the 


data are requested. 


new_state_ret returns the state of the ExportClient element after this request 
and can be set to one of the following standard export state values: 


xieValExportDone 
xieValExportMore 
xieValExportEmpty 
xieValExportError 


If the request is sent to an ExportClient element that either: does not have any 
data, was terminated by a previous XieGetClientData call, or has already 
returned all its data (ExportDone sent), the request will return a zero length 
data ret stream. 


Image data are always retrieved from the server as a byte stream, whereas 
nonimage data are always returned by the server as one or more complete 
aggregates. max_bytes is effectively rounded down by the server to the match 
the nearest aggregate size. 


For stored photoflos, name_space is always ServerIDSpace (the value zero) and 
flo_id is the photoflo's resource-id. For immediate photoflos name_space is a 
photospace resource-id and flo id is a 32-bit value that uniquely identifies the 
instance of the photoflo within name _ space. 


To free the memory allocated to data ret, use XFree. 


Structures 


typedef unsigned XieExportState; 
typedef unsigned XiePhototag; 


/* Definitions of ExportState */ 


#define xieValExportDone 1 
#define xieValExportMore 2 
#define xieValExportEmpty 3 
#define xieValExportError 4 

Errors 
xieErrNoFloAccess Executable photospace/flo id argument pair not active 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloElement Invalid element type specified by element 
xieErrNoFloID Invalid photospace/flo id argument pair has been 

specified 

xieErrNoFloValue Invalid band_number 

See Also 


XiePutClientData, XieQueryPhotoflo, XieExecutePhotoflo, 
XieFloExportClientHistogram, XieFloExportClientLUT, XieFloExportClientPhoto, 
XieFloExportClientROI 


XIElib - Abort and Await Functions XieAbort 


Name 
XieAbort - prematurely terminate execution of a photoflo 
Syntax 


void XieAbort (display, name_space, flo _ id); 
Display *display; 
unsigned long name_space; 
unsigned long flo id; 


Arguments 
display Specifies a connection to an X server. 
name_space Specifies the execution domain used for the photoflo to 
abort. 
flo_id Specifies a particular instance of the photoflo to abort. 
Description 


XieAbort will prematurely terminate execution of the photoflo specified by 
name _ space and flo id. Any output from the photoflo that is pending client 
retrieval is freed. Stored photoflos are returned to the inactive state; immediate 
photoflos are destroyed. 


If the photoflo specified by name_space and flo id is either invalid or not active, 
no action is taken; it is not an error, and nothing is destroyed. 


For stored photoflos, name_space is always ServerIDSpace (the value zero) and 
flo_id is the photoflo's resource-id. For immediate photoflos name_space is a 
photospace resource-id and flo id is 32-bit value that uniquely identifies the 
instance of the photoflo within name _ space. 


See Also 


XieExecutePhotoflo, XieExecuteImmediate 


XIElib - Abort and Await Functions XieAwait 


Name 


XieAwait - block all further requests for this client connection from being 
honored by the server while the photoflo is active 


Syntax 
void XieAwait (display, name_space, flo_ id); 
Display *display; 
unsigned long name_space; 
unsigned long flo id; 


Arguments 
display Specifies a connection to an X server. 
name _ space Specifies the execution domain used for the photoflo to 
block requests. 
flo_id Specifies a particular instance of the photoflo to block 
requests. 
Description 


XieAwait blocks all further requests for this client connection from being 
honored by the server while the photoflo, specified by name_ space and flo _ id, is 
active. When the photoflo transitions from the active state, blocked requests are 
allowed to be processed in the order received. 


If the photoflo specified by name_ space and flo id is either invalid or not active, 
no action is taken; it is not an error, and the client is not blocked. 


For stored photoflos, name_space is always ServerIDSpace (the value zero) and 
flo_id is the photoflo's resource-id. For immediate photoflos name_space is a 
photospace resource-id and flo id is 32-bit value that uniquely identifies the 
instance of the photoflo within name _ space. 


Warning 


Calling XieAwait before sending all import data or before retrieving all export 
data will block the client from sending or retrieving the remaining data. This 
also will prevent completion of the photoflo and prevent any and all protocol 
requests from this client from being honored. This deadlock can be broken only 
by another client completing or aborting the photoflo (to release the Await), or 
by breaking the client connection. 


Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 


See Also 


XieExecutePhotoFlo, XieExecuteImmediate 


XIElib - Photoflo Element Functions XieFloImportClientLUT 


Name 


XieFloImportClientLUT - specify an ImportClientLUT element and set its 
parameters 


Syntax 


void XieFloImportClientLUT (element, data class, band_order, length, levels) 
XiePhotoElement *element; 
XieDataClass data class; 
XieOrientation band _ order; 
XieLTriplet length; 
XieLevels levels; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
data class Specifies the number of lookup arrays to expect. 
band _ order Specifies the order of triple band arrays. 
length Specifies the number of entries per array. 
levels Specifies the number of quantization levels represented 
per array. 
Description 


An ImportClientLUT element accepts lookup table data from the protocol 
stream. The transport of data through the protocol stream is accomplished using 
XiePutClientData. This data is accepted by the Point, ExportLUT, and 
ExportClientLUT elements. 


data class, which specifies the number of lookup arrays to expect, can be set to 
one of the following standard data class values: 


xieValSingleBand 
xieValTripleBand 


The length of each array should match the number of source image levels that 
will be remapped through the array. When a triple band image is to be remapped 
through a single band array, the length of the array should match the product of 
the source image levels of all three bands; in this case, band order specifies the 
order in which pixels from a triple band image should be combined to form 
indices for a single band array. band order can be set to one of the following 
standard orientation values: 


xieValLS First 
xieValMS First 


The least significant band of trichromatic data is the first band mentioned in the 
common name of the colorspace: for example, red is the least significant band of 
RGB data. When one LUT array is used with triple band data, the algorithm for 
computing combined array indices, based on band_order, is: 


LUT band LUT indexing algorithm for combining pixel values 

order 

LSFirst index = value[0] + value[1] x levels[0] + value[2] x levels[0] 
x levels[1] 


MSFirst index = value[2] + value[1] x levels[2] + value[0] x levels[2] 
x levels[1] 


When three LUT arrays are used, band _ order specifies whether this band 
corresponds with the least significant or most significant LUT array. Each array 
is transported as a separate data stream. For example, if the colorspace of the 
image data is RGB: 


[band | __ LSFirst MSFirst 
| o)7)FCCdT SCRedarray—————idT(C CS =Bluearray 


Structures 


XieFloImportClientLUT sets the XiePhotoElement structure field elemType to 
xieElemImportClientLUT, which identifies the element as an ImportClientLUT, 
and sets the fields of the member structure ImportClientLUT using the 
arguments in the argument list. 


typedef unsigned XieDataClass; 
typedef unsigned XieOrientation; 
typedef unsigned long XieLTriplet[3]; 
typedef unsigned long XieLevels[3]; 


typedef struct { 
int elemType; 
union { 


struct { 
XieDataClass data_class; 
XieOrientation band_ order; 
XieLTriplet length; 
XieLevels levels; 

} ImportClientLUT; 


} data; 
} XiePhotoElement; 


/* Definitions of DataClass */ 


#define xieValSingleBand 1 
#define xieValTripleBand 2 
/* Definitions of Orientation Types */ 

#define xieValLSFirst 1 
#define xieValMSFirst 2 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 


xieErrNoFloMatch levels is incompatible with the server's depth-handling 
capabilities 
xieErrNoFloValue Invalid data_class or band_order 


See Also 


XiePutClientData, XieQueryPhotoflo, XieFloExportLUT, XieFloExportClientLUT, 
XieFloPoint, XieFloImportLUT 


XIElib - Photoflo Element Functions XieFloImportClientPhoto 


Name 


XieFloImportClientPhoto - specify an ImportClientPhoto element and set its 
parameters 


Syntax 


void XieFloImportClientPhoto (element, data class, width, height, levels, notify, 
decode_tech, decode_param) 
XiePhotoElement *element; 
XieDataClass data_class; 
XieLTriplet width; 
XieLTriplet height; 
XieLevels levels; 
Bool notify; 
XieDecodeTechnique decode tech; 
XiePointer decode param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
data class Specifies whether the data is single band or triple band. 
width Specifies the width of the image in pixels per band. 
height Specifies the height of the image in pixels per band. 
levels Specifies the number of quantization levels per band. 
notify Specifies whether to enable sending DecodeNotify 
events. 
decode tech Specifies the decode technique required to interpret the 
image. 
decode param Specifies the list of additional parameters required by 
decode tech. 
Description 


An ImportClientPhoto element accepts image data from the protocol stream. 
This data may be processed for display or used as process domain data. A 
process domain is inserted in many element definitions and is used to restrict 
the element's processing to a subset of the source data pixels. The attributes and 
organization of the expected data stream are fully specified by the parameters. 
The actual transport of image data through the protocol stream is requested 
using XiePutClientData. 


notify enables DecodeNotify events to be sent if anomalies are encountered 
while interpreting the imported image data: either an error has been 
encountered while decoding an image or the image data received does not 
satisfy the expected dimensions. 


Only constrained data can be sent through the protocol stream; therefore, levels 
must be valid. 


data _ class specifies whether the data is single band or triple band and can be set 
to one of the following standard data class values: 


xieValSingleBand 
xieValTripleBand 


Decode techniques define the techniques that can be used to interpret 
uncompressed image data or decode compressed images. decode_tech can be 
assigned one of the following standard decode technique values: 


xieValDecodeUncompressedSingle 
xieValDecodeUncompressedTriple 
xieValDecodeG31D 
xieValDecodeG32D 
xieValDecodeG42D 
xieValDecodeJPEGBaseline 
xieValDecodeJPEGLossless 
xieValDecodeTIFF2 
xieValDecodeTIFFPackBits 


If a vendor defined additional private decode techniques, the values given to 
these techniques can be assigned to decode_tech. 


Output Attributes 
Class class of imported image 
Type constrained 
Width width of imported image (in pixels) 
Height height of imported image (in pixels) 
Levels levels of imported image 
Structures 


XieFloImportClientPhoto sets the XiePhotoElement structure field elemType to 
xieElemImportClientPhoto, which identifies the element as an 
ImportClientPhoto, and sets the fields of the member structure 
ImportClientPhoto using the arguments in the argument list. 


typedef unsigned XieDataClass; 
typedef unsigned XieDecodeTechnique; 
typedef unsigned long XieLTriplet[3]; 
typedef unsigned long XieLevels[3]; 


typedef struct { 
int elemType; 
union { 


struct { 
XieDataClass data_class; 
XieLTriplet width; 
XieLTriplet height; 
XieLevels levels; 
Bool notify; 
XieDecodeTechnique decode _ tech; 
XiePointer decode param; 
} ImportClientPhoto; 


} data; 
} XiePhotoElement; 


/* Definitions of DataClass */ 


#define xieValSingleBand 1 
#define xieValTripleBand 2 
/* Definitions for DecodeTechniques */ 
#define xieValDecodeUncompressedSingle 2 
#define xieValDecodeUncompressedTriple 3 
#define xieValDecodeG31D 4 
#define xieValDecodeG32D 6 
#define xieValDecodeG42D 8 
#define xieValDecodeJPEGBaseline 10 
#define xieValDecodeJPEGLossless 12 
#define xieValDecodeTIFF2 14 
#define xieValDecodeTIFFPackBits 16 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloMatch levels is incompatible with the server's depth-handling 
capabilities 
xieErrNoFloTechnique Invalid decode tech or decode param 
xieErrNoFloValue Invalid width, height, levels (zero) or 


invalid data_ class 
See Also 


XieTecDecodeUncompressedSingle, XieTecDecodeUncompressedTriple, 
XieTecDecodeG31D, XieTecDecodeG32D, XieTecDecodeG42D, 
XieTecDecodeTIFF2, XieTecDecodeTIFFPackBits, XieTecDecodeJPEGBaseline, 
XieTecDecodeJPEGLossless 


XIElib - Photoflo Element Functions XieFloImportClientROI 


Name 


XieFloImportClientROI - specify an ImportClientROI element and set its 
parameters 


Syntax 


void XieFloImportClientROI (element, rectangles); 
XiePhotoElement *element; 
unsigned int rectangles; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
rectangles Specifies the number of rectangles expected. 
Description 


An ImportClientROI element accepts a list of rectangles from the protocol 
stream. These data can be used as input to a process domain or an ExportROI or 
ExportClientROI element. A process domain is inserted in many element 
definitions and is used to restrict the element's processing to a subset of the 
source data pixels. The actual transport of data through the protocol stream is 
accomplished using XiePutClientData (the band_number parameter of 
XiePutClientData is ignored). 


Structures 


XieFloImportClientROI sets the XiePhotoElement structure field elemType to 
xieElemImportClientROI, which identifies the element as an ImportClientROI, 
and sets the fields of the member structure ImportClientROI using the 
arguments in the argument list. 


typedef struct { 
int elemType; 
union { 
struct { 
unsigned int rectangles; 
} ImportClientROI; 
} data; 
} XiePhotoElement; 


Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
See Also 


XiePutClientData, XieQueryPhotoflo 
XieFIoExportROI, XieFloExportClientROI, XieFloImportROI 


XIElib - Photoflo Element Functions XieFloImportDrawable 


Name 


XieFloImportDrawable - 


Syntax 


specify an ImportDrawable element and set its 
parameters 


void XieFloImportDrawable (element, drawable, src_x, src_y, width, height, fill, 


notify) 


XiePhotoElement *element; 


Drawable drawable; 


int src_x; 

int src_y; 

unsigned int width; 
unsigned int height; 
unsigned long fill; 
Bool notify; 


Arguments 
element 
drawable 
sTc_Xx 
src_y 
width 
height 
fill 


notify 


Description 


Specifies the XiePhotoElement structure to use. 
Specifies the Drawable resource supplying the data. 
Specifies the left corner of the region of the data to be 
imported. 

Specifies the upper corner of the region of the data to 
be imported. 

Specifies the width of the region of the data to be 
imported. 

Specifies the height of the region of the data to be 
imported. 

Specifies the Colormap index to use for all regions that 
are obscured. 

Specifies whether to enable sending ImportObscured 
events. 


An ImportDrawable element allows access to data existing in a Drawable. This 
data may be processed for display or, if drawable is one bit deep, used as 
process domain data. A process domain is inserted in many element definitions 
and is used to restrict the element's processing to a subset of the source data 


pixels. 


notify enables ImportObscured events to be sent if data for one or more regions 
of a Window are obscured and cannot be retrieved from backing store. The 
arguments src_x, src_y, width, and height specify the region of data to be 
imported from drawable, where src_x and src_y define the upper-left corner of 


the region. 


Output Attributes 


Class 


single band 


Type constrained 


Width width 

Height height 

Levels 2depth (that is, drawable depth) 
Structures 


XieFloImportDrawable sets the XiePhotoElement structure field elemType to 
xieElemImportDrawable, which identifies the element as an ImportDrawable, 
and sets the fields of the member structure ImportDrawable using the 
arguments in the argument list. 


typedef struct { 
int elemType; 
union { 


struct { 
Drawable drawable; 
int src_x; 
int src_y; 
unsigned int width; 
unsigned int height; 
unsigned long fill; 
Bool notify; 

} ImportDrawable; 


} data; 
} XiePhotoElement; 
Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDrawable Invalid drawable 


xieErrNoFloValue Invalid region width, height, src_x, src_y 


XIElib - Photoflo Element 


Functions 


Name 


XieFloImportDrawablePlane 


XieFloImportDrawablePlane - specify an ImportDrawablePlane element and set 


Syntax 


its parameters 


void XieFloImportDrawablePlane (element, drawable, src_x, src_y, width, height, 


fill, bit_plane, notify) 


XiePhotoElement *element; 


Drawable drawable; 
int src_x; 

int src_y; 

unsigned int width; 
unsigned int height; 
unsigned long fill; 


unsigned long bit_plane; 


Bool notify; 


Arguments 


element 
drawable 
src_X 


src_y 
width 
height 
fill 


bit plane 
notify 


Description 


Specifies the XiePhotoElement structure to use. 
Specifies the Drawable resource supplying the data. 
Specifies the left corner of the region of the data to be 
imported. 

Specifies the upper corner of the region of the data to 
be imported. 

Specifies the width of the region of the data to be 
imported. 

Specifies the height of the region of the data to be 
imported. 

Specifies the Colormap index to use for all regions that 
are obscured. 

Specifies the plane to be imported from drawable. 
Specifies whether to enable sending ImportObscured 
events. 


An ImportDrawablePlane event allows access to a single plane of data existing in 
a Drawable. This data may be processed for display or used as process domain 
data. A process domain is inserted in many element definitions and is used to 
restrict the element's processing to a subset of the source data pixels. 


notify enables ImportObscured events to be sent if data for one or more regions 
of a Window are obscured and cannot be retrieved from backing store. The 
arguments src_x, src_y, width, and height specify the region of data to be 
imported from drawable, where src_x and src_y define the upper-left corner of 


the region. 


bit_plane must have exactly one bit set to one (1), and the value of bit_plane 
must be less than or equal to , where n is the depth of drawable. This single bit 
selects the corresponding bit to be extracted from pixels within drawable. 


Output Attributes 
Class single band 
Type constrained 
Width width 
Height height 
Levels 2 
Structures 


XieFloImportDrawablePlane sets the XiePhotoElement structure field elemType 
to xieElemImportDrawablePlane, which identifies the element as an 
ImportDrawablePlane, and sets the fields of the member structure 
ImportDrawablePlane using the arguments in the argument list. 


typedef struct { 
int elemType; 
union { 


struct { 
Drawable drawable; 
int src_x; 
int src_y; 
unsigned int width; 
unsigned int height; 
unsigned long fill; 
unsigned long bit plane; 
Bool notify; 

} ImportDrawablePlane; 


} data; 
} XiePhotoElement; 
Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDrawable Invalid drawable 
xieErrNoFloValue Invalid bit plane or region width, height, src_x, src_y 


XIElib - Photoflo Element Functions XieFloImportLUT 


Name 
XieFloImportLUT - specify an ImportLUT element and set its parameters 
Syntax 


void XieFloImportLUT (element, lut) 
XiePhotoElement *element; 


XieLut lut; 
Arguments 
element Specifies the XiePhotoElement structure to use. 
lut Specifies the LUT resource supplying the lookup table. 
Description 


An ImportLUT element allows access to lookup table data existing in a LUT 
resource. These data are accepted by the Point, ExportLUT, and ExportClientLUT 
elements. 


Attributes of the lookup table data are inherited from lut. 
Structures 


XieFloImportLUT sets the XiePhotoElement structure field elemType to 
xieElemImportLUT, which identifies the element as an ImportLUT, and sets the 
fields of the member structure ImportLUT using the arguments in the argument 
list. 


typedef XID XieLut; 


typedef struct { 
int elemType; 
union { 


struct { 
XieLut lut; 
} ImportLUT; 


} data; 
} XiePhotoElement; 
Errors 


xieErrNoFloAccess Attempt to import from Jut before it has been populated 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloLUT An unknown lut has been specified 


XIElib - Photoflo Element Functions XieFloImportPhotomap 


Name 


XieFloImportPhotomap - specify an ImportPhotomap element and set its 
parameters 


Syntax 


void XieFloImportPhotomap (element, photomap, notify) 
XiePhotoElement *element; 
XiePhotomap photomap; 


Bool notify; 
Arguments 
element Specifies the XiePhotoElement structure to use. 
photomap Specifies the photomap resource supplying image data. 
notify Specifies whether to enable sending DecodeNotify 
events. 
Description 


An ImportPhotomap element allows access to image data existing in a photomap; 
a photomap is a server resource that can be used to store image data. This data 
may be processed for display or used as process domain data (if its levels 
attribute is 2), or it may be used as source to ExportPhotomap or 
ExportClientPhoto or any other element which takes image data as input. A 
process domain is inserted in many element definitions and is used to restrict 
the element's processing to a subset of the source data pixels. 


notify enables DecodeNotify events to be sent if anomalies are encountered 
while decoding compressed data: either an error has been encountered while 
decoding an image or the image data received does not satisfy the expected 
dimensions. 


Attributes of the source data are inherited from photomap. 


Output Attributes 
Class same as photomap 
Type same as photomap 
Width same as photomap 
Height same as photomap 
Levels same as photomap 
Structures 


XieFloImportPhotomap sets the XiePhotoElement structure field elemType to 
xieElemImportPhotomap, which identifies the element as an ImportPhotomap, 
and sets the fields of the member structure ImportPhotomap using the 
arguments in the argument list. 


typedef XID XiePhotomap; 


typedef struct { 
int elemType; 


union { 
struct { 
XiePhotomap photomap; 
Bool notify; 
} ImportPhotomap; 
} data; 
} XiePhotoElement; 
Errors 
xieErrNoFloAccess Attempt to import from photomap before it has been 
populated 
xieErrNoFloAlloc Insufficient resources (for example, memory) 


xieErrNoFloPhotomap An unknown photomap has been specified 


See Also 
XieFloExportPhotomap, XIeFloExportClientPhoto 


XIElib - Photoflo Element Functions XieFloImportROI 


Name 
XieFloImportROI - specify an ImportROI element and set its parameters 
Syntax 


void XieFloImportROI (element, roi) 
XiePhotoElement *element; 


XieRoi roi; 
Arguments 
element Specifies the XiePhotoElement structure to use. 
roi Specifies the ID of the ROI supplying the list-of- 
rectangles. 
Description 


An ImportROI element allows access to a list-of-rectangles existing in a ROI 
resource. This data may be referenced by a process domain, or used as input to 
an ExportClientROI or ExportROI element. A process domain is inserted in many 
element definitions and is used to restrict the element's processing to a subset of 
the source data pixels. 


Structures 


XieFloImportROI sets the XiePhotoElement structure field elemType to 
xieElemImportROI, which identifies the element as an ImportROI, and sets the 
fields of the member structure ImportROI using the arguments in the argument 
list. 


typedef XID XieRoi; 


typedef struct { 
int elemType; 
union { 


struct { 
XieRoi roi; 
} ImportROI; 
} data; 
} XiePhotoElement; 
Errors 


xieErrNoFloAccess Attempt to import from roi before it has been populated 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloPhotomap An unknown roi has been specified 


See Also 
XieFIOExportROI, XieFloExportClientROI 


XIElib - Photoflo Element Functions XieFloArithmetic 


Name 


XieFloArithmetic - specify an Arithmetic element and set its parameters 


Syntax 


void XieFloArithmetic (element, src1, src2, domain, constant, operator, 

band_mask) 

XiePhotoElement *element; 

XiePhototag src1; 

XiePhototag src2; 

XieProcessDomain *domain; 

XieConstant constant; 

XieArithmeticOp operator; 

unsigned int band_mask; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
srcl Specifies the phototag of the first data source. 
src2 Specifies the phototag of the second data source, or 0 if 
none. 
domain Specifies the subset of source data that will be operated 
on. 
constant Specifies the constant data source (if src2 is 0). 
operator Specifies the arithmetic operation to be performed. 
band_mask Specifies which bands are to be operated on. 
Description 


An Arithmetic element produces output data by performing an addition, 
subtraction, minimum, or maximum operation between two data sources or 
between a single data source and a constant. Furthermore, multiplication, 
division, or gamma correction may by applied to a single data source. 


When two sources are involved, src1 and src2 are the phototags of the elements 
supplying source data (constant is ignored). A phototag is the position or index 
of an element within an array of elements used to specify a photoflo; the first 
element in the array has a phototag value of one (1). If the operation is to involve 
a constant, srci is one operand, src2 must be zero, and constant is used as the 
other operand. 


When two sources are involved, all attributes, other than width and height, must 
match; all output attributes are inherited from src1. 


In order to specify a subset of source data that will be operated on, the phototag, 
offset_x, and offset_y fields of the XieProcessDomain structure pointed to by 
domain must be supplied; XIElib does not provide a convenience function to 
create and/or fill in an XieProcessDomain structure. If the entire source data is 
to be operated on, a pointer to an XieProcessDomain structure must still be 


provided, with the phototag field set to zero (0); the offset_x and offset _y fields 
are ignored. 


Only bands selected by band_mask are subject to processing. Other bands 
present in the image are passed through to the output. For example, a 
band_mask of 0012 indicates that only the “least significant band” would be 
processed; operating on all bands requires a band mask of 1112. Using 
band_mask to select source data that have two (2) or less levels is not permitted. 


Pixel computations that would lead to errors, will yield valid server-dependent 
values (for example, dividing by a constrained pixel value of zero might result in 
a value of levels-1). 


The valid operations for the Arithmetic process element are: 


src1 (operator) src1 (operator) constant 
src2 


| xieValMul [src * constant 
| xieValDiv | src /constant 
| xieValDivRev | | constant /srel 


xieValMin minimum( srcl, minimum( srci1, constant ) 
src2 ) 

xieValMax maximum( srcl, maximum( src1, constant ) 
src2 ) 

xieValGamma (levels - 1) * ((src1 / (levels - 

(constrained) 1))constant) 


xieValGamma src 1 constant 
(unconstraine 
d) 
Output Attributes 
Class same as srcl 
Type same as srcl 
Width same as srcl 
Height same as srcl 
Levels same as srcl 
Structures 


XieFloArithmetic sets the XiePhotoElement structure field elemType to 
xieElemArithmetic, which identifies the element as an Arithmetic, and sets the 
fields of the member structure Arithmetic using the arguments in the argument 
list. 


typedef unsigned XiePhototag; 
typedef float XieConstant[3]; 
typedef unsigned XieArithmeticOp; 
typedef struct { 

int offset x; 

int offset _y; 


XiePhototag phototag; 
} XieProcessDomain; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src1; 
XiePhototag src2; 
XieProcessDomain domain; 
XieConstant constant; 
XieArithmeticOp operator; 
unsigned int band_mask; 

} Arithmetic; 


} data; 
} XiePhotoElement; 


/* Definitions of ArithmeticOperations */ 
#define xieValAdd 

#define xieValSub 

#define xieValSubRev 

#define xieValMul 

#define xieValDiv 

#define xieValDivRev 

#define xieValMin 

#define xieValMax 

#define xieValGamma 


OAONODUBWNRE 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDomain Invalid domain 
xieErrNoFloMatch Class, type, or levels differ between srci1 and src2 or 
selected data source are bitonal 
xieErrNoFloOperator Invalid operator 
xieErrNoFloSource Invalid src1 or src2 or 
src2 has been specified with a monadic operator 


XIElib - Photoflo Element Functions XieFloBandCombine 


Name 
XieFloBandCombine - specify a BandCombine element and set its parameters 
Syntax 


void XieFloBandCombine (element, src1, src2, src3) 
XiePhotoElement *element; 
XiePhototag src1; 
XiePhototag src2; 
XiePhototag src3; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
srcl Specifies the first element supplying source data. 
src2 Specifies the second element supplying source data. 
src3 Specifies the third element supplying source data. 
Description 


A BandCombine element merges three single band data sources to produce a 
triple band result. The arguments srcl1, src2, and src3 must be of the same type, 
and each source must be single band. Other attributes that are taken from the 
individual sources may differ. The output will be triple band. 


Output Attributes 
Class triple band 
Type same as srcl 
Width same as srcs 
Height same as srcs 
Levels same as srcs 
Structures 


XieFloBandCombine sets the XiePhotoElement structure field elemType to 
xieElemBandCombine, which identifies the element as a BandCombine, and sets 
the fields of the member structure BandCombine using the arguments in the 
argument list. 


typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src1; 
XiePhototag src2; 
XiePhototag src3; 


} BandCombine; 


} data; 
} XiePhotoElement; 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloMatch A source has more than one band or 

type differs between sources 
xieErrNoFloSource Invalid src1, src2, or src3 


XIElib - Photoflo Element Functions XieFloBandExtract 


Name 


XieFloBandExtract - specify a BandExtract element and set its parameters 


Syntax 


void XieFloBandExtract (element, src, levels, bias, coefficients) 
XiePhotoElement *element; 
XiePhototag src; 
unsigned int levels; 
double bias; 
XieConstant coefficients; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
levels Specifies the number of quantization levels for the 
output. 
bias Specifies the value to be added to each output pixel. 
coefficients Specifies the proportion of each band in src to pixelsin 
the single band result. 
Description 


A BandExtract element produces single band output data from a triple band 
source by multiplying a pixel value from each source band by its corresponding 
coefficient and then summing the results with the bias value. 


coefficients is a three-element array that determines the proportion of each 
source band pixel that is used to form the output. levels is used as the levels 
attribute of the output data if the src data are constrained; otherwise, it is 
ignored. 


The source data must be triple band, and all bands must have equal dimensions. 
The output data will be single band, with levels taken from the levels parameter, 
if the data type is constrained. All other attributes are inherited from src. 


Output Attributes 

Class single band 

Type same as src 

Width same as src 

Height same as src 

Levels levels if src is contrained, else unknown 
Structures 


XieFloBandExtract sets the XiePhotoElement structure field elemType to 
xieElemBandExtract, which identifies the element as a BandExtract, and sets the 


fields of the member structure BandExtract using the arguments in the 
argument list. 


typedef float XieConstant[3]; 
typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
unsigned int levels; 
float bias; 
XieConstant coefficients; 
} BandExtract; 


} data; 
} XiePhotoElement; 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloMatch src is not triple band or 


unequal interband dimensions 
xieErrNoFloSource Invalid src 


XIElib - Photoflo Element Functions XieFloBandSelect 


Name 
XieFloBandSelect - specify a BandSelect element and set its parameters 
Syntax 


void XieFloBandSelect (element, src, band_number) 
XiePhotoElement *element; 
XiePhototag src; 
unsigned int band_number; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
band_number Specifies which src band is to be selected to provide the 
output data. 
Description 


A BandSelect element produces single band output data by selecting a single 
band from a triple band source. 


Output Attributes 
Class single band 
Type same as src 
Width same as band selected from src 
Height same as band selected from src 
Levels same as band selected from src 
Structures 


XieFloBandSelect sets the XiePhotoElement structure field elemType to 
xieElemBandSelect, which identifies the element as a BandSelect, and sets the 
fields of the member structure BandSelect using the arguments in the argument 
list. 


typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 
union { 


struct { 

XiePhototag src; 

unsigned int band_number; 
} BandSelect; 


} data; 
} XiePhotoElement; 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloMatch src is not triple band 
xieErrNoFloSource Invalid src 


xieErrNoFloValue Invalid band_number 


XIElib - Photoflo Element Functions XieFloBlend 


Name 


XieFloBlend - specify a Blend element and set its parameters 
Syntax 


void XieFloBlend (element, src1, src2, src_constant, alpha, alpha_const, domain, 
band_mask) 
XiePhotoElement *element; 
XiePhototag src1; 
XiePhototag src2; 
XieConstant src_constant; 
XiePhototag alpha; 
double alpha _ const; 
XieProcessDomain *domain; 
unsigned int band_mask; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
srcl Specifies the phototag of the first data source. 
src2 Specifies the phototag of the second data source, else 0. 
src_constant Specifies a constant data source, if src2 is 0. 
alpha Specifies the blend proportion for each processed pixel. 
alpha_const Specifies the constant blend proportion for each 
processed pixel. 
domain Specifies the subset of source data that will be operated 
on. 
band_mask Specifies which bands are to be operated on. 
Description 


A Blend element produces output data from two data sources or a single data 
source and a constant. Each output pixel is a percentage combination of the 
source values, as controlled by an alpha input image or an alpha constant. 


When two sources are involved, srci1 and src2 are the phototags of the elements 
supplying source data; src_constant is ignored. A phototag is the position or 
index of an element within an array of elements used to specify a photoflo; the 
first element in the array has a phototag value of one (1). If the operation is to 
involve a constant, src1 is one operand, src2 must be zero, and src_constant is 
used as the other operand. If alpha is nonzero, it controls the blend proportion 
for each pixel that is processed, otherwise alpha _ const provides this control. 
Domain may control the subset of source data that will be operated on. Only 
bands selected by the band _ mask are subject to processing. Other bands present 
in the image are passed through to the output. For example, a band_mask of 
0012 indicates that only the “least significant band” would be processed; 
operating on all bands requires a band_mask of 1112. Using band_mask to select 
source data that have two (2) or less levels is not permitted. 


When two sources are involved, all attributes, other that width and height, must 
match. If alpha is nonzero, it must be a source of constrained data. 


In order to specify a subset of source data that will be operated on, the phototag, 
offset_x, and offset_y fields of the XieProcessDomain structure pointed to by 
domain must be supplied; XIElib does not provide a convenience function to 
create and/or fill in an XieProcessDomain structure. If the entire source data is 
to be operated on, a pointer to an XieProcessDomain structure must still be 
provided, with the phototag field set to zero (0); the offset_x and offset _y fields 
are ignored. 


Within the intersection of the source(s) and domain, each output pixel is a blend 
of the corresponding pixels from src1 and src2 (or srci1 pixels blended with 
src_constant). The degree of blend is determined by the corresponding pixel 
taken from alpha or the value of alpha_const. If alpha is nonzero, the proportion 
of blend is further scaled by alpha _ const: 


output = srcl * (1 - alpha/ alpha const) + src2* (alpha / alpha_const) 
(where alpha const is greater than 0.0) 


if alpha is zero: 


output = srcl * (1 - alpha const) + src2 * alpha const 
(where alpha _ const is in the range [0.0, 1.0]) 


Output Attributes 
Class same as srcl 
Type same as srcl 
Width same as srcl 
Height same as srcl 
Levels same as srcl 
Structures 


XieFloBlend sets the XiePhotoElement structure field elemType to xieElemBlend, 
which identifies the element as a Blend, and sets the fields of the member 
structure Blend using the arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef float XieConstant[3]; 
typedef struct { 

int offset x; 

int offset _y; 

XiePhototag phototag; 
} XieProcessDomain; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src1; 
XiePhototag src2; 
XieConstant src_constant; 
XiePhototag alpha; 


float alpha constant; 
XieProcessDomain domain; 
unsigned int band_mask; 


} Blend; 
} data; 
} XiePhotoElement; 


Errors 


xieErrNoFloAlloc 
xieErrNoFloMatch 


xieErrNoFloSource 
xieErrNoFloValue 


Insufficient resources (for example, memory) 
Incompatible attributes between src1 and src2 or 
alpha is unconstrained or 

selected source data are bitonal 

Invalid src1, src2, or alpha 

alpha is zero and alpha_const is outside the range 
[0.0,1.0], or 

alpha is nonzero and alpha _const is nonpositive 


XIElib - Photoflo Element Functions XieFloCompare 


Name 
XieFloCompare - specify a Compare element and set its parameters 
Syntax 


void XieFloCompare (element, src1, src2, domain, constant, operator, combine, 

band_mask) 

XiePhotoElement *element; 

XiePhototag src1; 

XiePhototag src2; 

XieProcessDomain *domain; 

XieConstant constant; 

XieCompareOp operator; 

Bool combine; 

unsigned int band_mask; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
srcl Specifies the first data source. 
src2 Specifies the second data source. 
domain Specifies the subset of source data that will be operated 
on. 
constant Specifies the constant data source. 
operator Specifies the logical predicate operator used in the 
comparison. 
combine Specifies whether the comparison should be done ona 
per-band or on an all-bands basis. 
band_mask Specifies which bands are to be operated on. 
Description 


A Compare element takes two data sources or a single data source and a 
constant and generates a Boolean bitmap output that reflects the results of a 
pointwise comparison. The output data has a value of one wherever the 
comparison is true, and a value of zero everywhere else (that is, comparison 
false or comparison not performed). The comparison may be performed on a per- 
band basis or for all bands taken together. 


When two sources are involved, src1 and src2 are the phototags of the elements 
supplying source data; constant is ignored. A phototag is the position or index of 
an element within an array of elements used to specify a photoflo; the first 
element in the array has a phototag value of one (1). If the operation is to involve 
a constant, srci is one operand, src2 must be zero, and constant is used as the 
other operand. 


In order to specify a subset of source data that will be operated on, the phototag, 
offset_x, and offset_y fields of the XieProcessDomain structure pointed to by 
domain must be supplied; XIElib does not provide a convenience function to 
create and/or fill in an XieProcessDomain structure. If the entire source data is 


to be operated on, a pointer to an XieProcessDomain structure must still be 
provided, with the phototag field set to zero (0); the offset_x and offset_y fields 
are ignored. 


operator is the logical predicate operator used in the comparison. The valid 
operators for the Compare process element are: 


Operator srcl1 (operator) src2 srcl1 (operator) 
constant 


xieValLT 
xieValLE 


combine is a Boolean that determines whether the comparison should be done 
on a per-band basis or on an all-bands basis. Only bands selected by band_mask 
are subject to processing. Other bands present in the image are passed through 
to the output. For example, aband_ mask of 0012 indicates that only the “least 
significant band” would be processed; operating on all bands requires a 
band_mask of 1112. 


If combine is True or srcl is single band, the output data will form a single 
Boolean bitmap. If src1 is triple band and combine is False, the output data will 
yield three separate boolean bitmaps (for this case band_mask must specify all 
bands). 


If srci is triple band and combine is True, only the EQ and NE operators are 
allowed; equality is established for each band selected by band _mask, and then 
the result is logically ANDed to derive equality (inequality is a logical NOT of 
this result). For this case, width and height must match for all bands selected by 
band_mask. 


The relationship between combine and data class dependencies is given in the 
following table: 


True single band n/a single band 
| = stsésd:*SCstriple band selected bands single band 


single band single band 
| = stripe band all bands triple band 


Output Attributes 
Class see Description 
Type constrained 
Width same as srcl 
Height same as srcl 
Levels 2 per band (see Description) 


Structures 


XieFloCompare sets the XiePhotoElement structure field elemType to 
xieElemCompare, which identifies the element as a Compare, and sets the fields 
of the member structure Compare using the arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef float XieConstant[3]; 
typedef struct { 

int offset _x; 

int offset _y; 

XiePhototag phototag; 
} XieProcessDomain; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src1; 
XiePhototag src2; 
XieProcessDomain domain; 
XieConstant constant; 
XieCompareOp operator; 
Bool combine; 
unsigned int band_mask; 

} Compare; 


} data; 
} XiePhotoElement; 


/* Definitions of Compare Operators */ 
#define xieValLT 
#define xieValLE 
#define xieValEQ 
#define xieValNE 
#define xieValGT 
#define xieValGE 


OuURWNR 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 

xieErrNoFloDomain Invalid domain 

xieErrNoFloMatch Class differs between src1 and src2 or 
invalid combination of operator and combine or 
triple band, and combine is false, and band_mask 
incomplete 

xieErrNoFloOperator Invalid operator 

xieErrNoFloSource Invalid src1 or src2 


XIElib - Photoflo Element Functions XieFloConstrain 


Name 


XieFloConstrain - specify a Constrain element and set its parameters 
Syntax 


void XieFloConstrain (element, src, levels, constrain_tech, constrain_param) 
XiePhotoElement *element; 
XiePhototag src; 
XieLevels levels; 
XieConstrainTechnique constrain_ tech; 
XiePointer constrain_param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
levels Specifies the number of quantization levels desired in 
the output data. 
constrain tech Specifies the technique to be used when constraining 
the data. 
constrain param Specifies the list of additional parameters required by 
constrain. 
Description 


A Constrain element applies a quantization model to the image data to convert 
the data to a fixed number of quantization levels. Application of the quantization 
model may involve steps such as range shifting, scaling, clipping, and rounding. 


src is the phototag of the element supplying source data. A phototag is the 
position or index of an element within an array of elements used to specify a 
photoflo; the first element in the array has a phototag value of one (1). Levels is 
the number of quantization levels desired in the output data. constrain_ tech 
specifies the constrain technique to be used when constraining the data. 
constrain_param is the list of additional parameters required by constrain_tech. 


If the input image is already constrained, the data will be reconstrained. 


One of the following standard constrain technique values can be assigned to 
constrain_tech : 


xieValConstrainClipScale 
xieValConstrainHardClip 


If a vendor defined additional private constrain techniques, the values given to 
these techniques can be assigned to constrain_tech. 


Output Attributes 


Class same aS src 


Type constrained 

Width same as src 

Height same as src 

Levels levels 
Structures 


XieFloConstrain sets the XiePhotoElement structure field elemType to 
xieElemConstrain, which identifies the element as a Constrain, and sets the 
fields of the member structure Constrain using the arguments in the argument 
list. 


typedef unsigned XiePhototag; 
typedef unsigned long XieLevels[3]; 
typedef unsigned XieConstrainTechnique; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieLevels levels; 
XieConstrainTechnique constrain_tech; 
XiePointer constrain_param; 

} Constrain; 


} data; 
} XiePhotoElement; 


/* Definitions for ConstrainTechniques */ 


#define xieValConstrainClipScale 2 
#define xieValConstrainHardClip 4 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloSource Invalid src 


xieErrNoFloTechnique Invalid constrain tech or constrain param 
See Also 
XieTecClipScale 


XIElib - Photoflo Element FunctionsXieFloConvertFromIndex 


Name 


XieFloConvertFromIndex - specify a ConvertFromIndex element and set its 
parameters 


Syntax 


void XieFloConvertFromIndex (element, src, colormap, data _class, precision) 
XiePhotoElement *element; 
XiePhototag src; 
Colormap colormap; 
XieDataClass data class; 
unsigned int precision; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
colormap Specifies the Colormap from which to obtain output 
pixel values. 
data class Specifies whether the output data is single band or 
triple band. 
precision Specifies the number of bits to be used from colormap's 
RGB values. 
Description 


A ConvertFromIndex element converts Colormap index data into achromatic or 
trichromatic data. 


data class specifies whether the output data is single band or triple band and 
can be set to one of the following standard data class values: 


xieValSingleBand 
xieValTripleBand 


If data_class is single band and a trichromatic colormap is specified (static color, 
pseudo color, true color, or direct color), the gray shade for each pixel is taken 
from the red values in colormap. If data class is triple band and an achromatic 
colormap is specified (static gray or gray scale), the red band will be replicated 
to populate the green and blue output bands. 


The depth of colormap must match the Levels attribute of src (that is, 2depth 
must equal Levels). 


Output Attributes 
Class data class 
Type constrained 


Width same as src 


Height same as src 
Levels 2precision (per band) 


Structures 


XieFloConvertFromIndex sets the XiePhotoElement structure field elemType to 
xieElemConvertFromIndex, which identifies the element as a ConvertFromIndex, 
and sets the fields of the member structure ConvertFromIndex using the 
arguments in the argument list. 


typedef unsigned XieDataClass; 
typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
Colormap colormap; 
XieDataClass data_class; 
unsigned int precision; 

} ConvertFromIndex; 


} data; 
} XiePhotoElement; 


/* Definitions of DataClass */ 


#define xieValSingleBand 1 
#define xieValTripleBand 2 

Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloColormap Invalid colormap 
xieErrNoFloMatch Levels of src do not match depth of colormap 
xieErrNoFloSource Invalid src 


xieErrNoFloValue Invalid data_class or precision 


XIElib - Photoflo Element Functions XieFloConvertFromRGB 


Name 


XieFloConvertFromRGB - specify a ConvertFromRGB element and set its 
parameters 


Syntax 


void XieFloConvertFromRGB (element, src, color space, color_param) 
XiePhotoElement *element; 
XiePhototag src; 
XieColorspace color space; 
XiePointer color param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data (RGB 
assumed). 
color _space Specifies the technique to be used in the conversion. 
color param Specifies the list of additional parameters required by 
color_ space. 
Description 


A ConvertFromRGB element converts RGB source data to an alternate 
colorspace. 


The source data must be triple band, and all bands must have equal dimensions. 
The type and levels of the output data are determined by the color space's 
technique parameters. All other attributes are inherited from src. 


ConvertFromRGB techniques define the trichromatic colorspaces known to a 
ConvertFromRGB element. One of the following standard ConvertFromRGB 
technique values can be assigned to color space: 


xieValRGBToCIELab 
xieValRGBToCIEXYZ 
xieValRGBToYCbCr 
xieValRGBToYCC 


If a vendor defined additional private ConvertFromRGB techniques, the private 
technique values given to these techniques can be assigned to color space. 


Output Attributes 
Class triple band 
Type color space dependent 
Width same as src 
Height same as src 


Levels color space dependent 


Structures 


XieFloConvertFromRGB sets the XiePhotoElement structure field elemType to 
xieElemConvertFromRGB, which identifies the element as a ConvertFromRGB, 
and sets the fields of the member structure ConvertFromRGB using the 
arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef unsigned XieColorspace; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieColorspace color space; 
XiePointer color param; 

} ConvertFromRGB; 


} data; 
} XiePhotoElement; 


/* Definitions for Colorspace Conversions */ 


#define xieValRGBToCIELab 2 
#define xieValRGBToCIEXYZ 4 
#define xieValRGBToYCbCr 6 
#define xieValRGBToYCC 8 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloMatch src is not triple band or 
unequal inter-band dimensions 
xieErrNoFloSource Invalid src 


xieErrNoFloTechnique Invalid color space or color param 


See Also 


XieFloConvertToRGB, XieTecRGBToCIELab, XieTecRGBToCIEXYZ, 
XieTecRGBToYCbCr, XieTecRGBToYCC 


XIElib - Photoflo Element Functions XieFloConvertToIndex 


Name 


XieFloConvertToIndex - specify a ConvertToIndex element and set its parameters 
Syntax 


void XieFloConvertToIndex (element, src, colormap, color list, notify, 
color _alloc_tech, color _alloc_param) 
XiePhotoElement *element; 
XiePhototag src; 
Colormap colormap; 
XieColorList color list; 
Bool notify; 
XieColorAllocTechnique color alloc_tech; 
XiePointer color alloc_param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying the constrained source 
data. 
colormap Specifies the Colormap from which to obtain output 
pixel values. 
color list Specifies the list where Colormap indices are to be 
stored. 
notify Specifies whether to enable sending ColorAlloc events. 
color_alloc_tech Specifies the desired color allocation technique. 
color_alloc_ param Specifies the list of additional parameters required by 
color_alloc_tech. 
Description 


A ConvertToIndex element allocates and/or matches colors or gray shades, as 
required, from a Colormap. It produces pixel indices as output data, and records 
indices that it allocates in color list. 


The specified color _alloc_tech technique may generate a ColorAlloc event to 
warn the client that results are of lesser fidelity than desired. Notify allows the 
client to be notified about inferior results from color allocation or matching. 


src is the phototag of the element supplying constrained source data. A phototag 
is the position or index of an element within an array of elements used to specify 
a photoflo; the first element in the array has a phototag value of one (1). 
Colormap is the Colormap from which colors or gray shades are allocated and/or 
matched. Color list is the list where allocated Colormap indices are to be stored. 
color _alloc_tech specifies the desired color allocation technique. 

color _alloc_params is the list of additional parameters required by 
color_alloc_tech. 


color list is purged of any colors it already contains when photoflo execution 
begins. Allocated Colormap indices can be freed using XiePurgeColorList, 


XieDestroyColorList, or by making color list the target of an active photoflo. 
Care must be taken to ensure that color list is not referenced by more than one 
executing photoflo at any time; it is a protocol error to allow more than one 
executing photoflo access the same color list. 


ColorAlloc techniques define the recognized color allocation techniques used by 
the ConvertToIndex element. One of the following standard ColorAlloc technique 
values can be assigned to color _alloc_tech: 


xieValColorAllocDefault 
xieValColorAllocAll 
xieValColorAllocMatch 
xieValColorAllocRequantize 


If a vendor defined additional private ColorAlloc techniques, the private 
technique values given to these techniques can be assigned to color alloc_tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Output Attributes 

Class single band 

Type constrained 

Width same as src 

Height same as src 

Levels 2depth (that is, colormap depth) 
Structures 


XieFloConvertToIndex sets the XiePhotoElement structure field elemType to 
xieElemConvertToIndex, which identifies the element as a ConvertToIndex, and 
sets the fields of the member structure ConvertToIndex using the arguments in 
the argument list. 


typedef unsigned XiePhototag; 
typedef XID XieColorList; 
typedef unsigned XieColorAllocTechnique; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
Colormap colormap; 
XieColorList color list; 
Bool notify; 
XieColorAllocTechnique color alloc tech; 
XiePointer color_alloc_param; 
} ConvertToIndex; 


} data; 
} XiePhotoElement; 


/* Definitions for ColorAlloc Techniques */ 


#define xieValColorAllocDefault 0 
#define xieValColorAllocAll 2 
#define xieValColorAllocMatch 4 
#define xieValColorAllocRequantize 6 
Errors 
xieErrNoFloAccess color list already being used by another active photoflo 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloColorlist Invalid color list 
xieErrNoFloColormap Invalid colormap 
xieErrNoFloMatch Unequal inter-band dimensions 


xieErrNoFloSource Invalid src 
xieErrNoFloTechnique Invalid color alloc tech or color _alloc_param 


See Also 


XieCreateColorList, XiePurgeColorList, XieDestroyColorList 
XieTecColorAllocAll, XieTecColorAllocMatch, XieTecColorAllocRe quantize 


XIElib - Photoflo Element Functions XieFloConvertToRGB 


Name 
XieFloConvertToRGB - specify a ConvertToRGB element and set its parameters 
Syntax 


void XieFloConvertToRGB (element, src, color space, color_param) 
XiePhotoElement *element; 
XiePhototag src; 
XieColorspace color space; 
XiePointer color param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
color space Specifies the technique that will be used for the 
conversion. 
color_param Specifies the list of additional parameters required by 
color_space. 
Description 


A ConvertToRGB element converts alternate colorspace source data into RGB 
data. 


The source data must be triple band, and all bands must have equal dimensions. 
The type and levels of the output data are determined by the color space's 
technique parameters. All other attributes are inherited from src. 


ConvertToRGB techniques define the trichromatic colorspaces known to a 
ConvertToRGB element. One of the following standard ConvertFromRGB 
technique values can be assigned to color space: 


xieValCIELabToRGB 
xieValCIEXYZToRGB 
xieValYCbCrToRGB 
xieValYCCToRGB 


If a vendor defined additional private ConvertToRGB techniques, the private 
technique values given to these techniques can be assigned to color space. 


Output Attributes 
Class triple band 
Type color space dependent 
Width same as src 
Height same as src 


Levels color_space dependent 


Structures 


XieFloConvertToRGB sets the XiePhotoElement structure field elemType to 
xieElemConvertToRGB, which identifies the element as a ConvertToRGB, and 
sets the fields of the member structure ConvertToRGB using the arguments in 
the argument list. 


typedef unsigned XieColorspace; 
typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieColorspace color space; 
XiePointer color param; 

} ConvertToRGB; 


} data; 
} XiePhotoElement; 


/* Definitions for Colorspace Conversions */ 


#define xieValCIELabToRGB 2 
#define xieValCIEXYZToRGB 4 
#define xieValYCbCrIToRGB 6 
#define xieValYCCToRGB 8 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloMatch src is not triple band or 
unequal inter-band dimensions 
xieErrNoFloSource Invalid src 


xieErrNoFloTechnique Invalid color space or color param 


See Also 


XieTecCIELabToRGB, XieTecCIEXYZToORGB, XieTecYCbCrToRGB, 
XieTecYCCToRGB, XieConvertFromRGB 


XIElib - Photoflo Element Functions XieFloConvolve 


Name 


XieFloConvolve - specify a Convolve element and set its parameters 


Syntax 


void XieFloConvolve (element, src, domain, kernel, kernel_size, band_mask, 
convolve_tech, convolve_param) 
XiePhotoElement *element; 
XiePhototag src; 
XieProcessDomain *domain; 
float *kernel; 
int kernel size; 
unsigned int band_mask; 
XieConvolveTechnique convolve_ tech; 
XiePointer convolve_param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
domain Specifies the subset of the image that will be operated 
on. 
kernel Specifies the coefficients used in the convolution 
process. 
kernel_size Specifies the dimension of kernel. 
band_mask Specifies which bands are to be operated on. 
convolve_tech Specifies the technique for handling edge conditions. 
convolve_param Specifies the list of additional parameters required by 
convolve_tech. 
Description 


A Convolve element produces output data by convolving each input pixel value 
(and surrounding area) with the specified convolution kernel. 


In order to specify a subset of source data that will be operated on, the phototag, 
offset_x, and offset_y fields of the XieProcessDomain structure pointed to by 
domain must be supplied; XIElib does not provide a convenience function to 
create and/or fill in an XieProcessDomain structure. If the entire source data is 
to be operated on, a pointer to an XieProcessDomain structure must still be 
provided, with the phototag field set to zero (0); the offset_x and offset _y fields 
are ignored. 


kernel represents a square array of float data that has odd dimensions. Thus, a 
single dimension is used to specify kernel size. 


Only bands selected by the band _mask are subject to processing. Other bands 
present in the image are passed through to the output. For example, a 
band_mask of 0012 indicates that only the “least significant band” would be 


processed; operating on all bands requires a band mask of 1112. Using 
band_mask to select source data that have two (2) or less levels is not permitted. 


All output data attributes are inherited from the source data. 


Convolve techniques provide various methods of handling edge conditions. 
These techniques determine what pixel values are used when Convolve requires 
data beyond the image bounds. One of the following standard convolve 
technique values can be assigned to convolve_tech: 


xieValConvolveDefault 
xieValConvolveConstant 
xieValConvolveReplicate 


If a vendor defined additional private convolve techniques, the private technique 
values given to these techniques can be assigned to convolve_tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined above or a private technique. 


Output Attributes 
Class same as src 
Type same as src 
Width same as src 
Height same as src 
Levels same as src 
Structures 


XieFloConvolve sets the XiePhotoElement structure field elemType to 
xieElemConvolve, which identifies the element as a Convolve, and sets the fields 
of the member structure Convolve using the arguments in the argument list. 


typedef unsigned XieConvolveTechnique; 
typedef unsigned XiePhototag; 
typedef struct { 
int offset_x; 
int offset _y; 
XiePhototag phototag; 
} XieProcessDomain; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieProcessDomain domain; 
float *kernel; 
int kernel size; 
unsigned int band_mask; 
XieConvolveTechnique convolve tech; 
XiePointer convolve_ param; 
} Convolve; 


} data; 
} XiePhotoElement; 


/* Definitions for ConvolveTechniques */ 


#define xieValConvolveDefault 0 
#define xieValConvolveConstant 2 
#define xieValConvolveReplicate 4 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDomain Invalid domain 
xieErrNoFloMatch Selected source data are bitonal 
xieErrNoFloSource Invalid src 
xieErrNoFloTechnique Invalid convolve tech or convolve_param 
xieErrNoFloValue Invalid kernel size (for example, not odd) 
See Also 


XieTecConvolveConstant 


XIElib - Photoflo Element Functions XieFloDither 


Name 
XieFloDither - specify a Dither element and set its parameters 
Syntax 


void XieFloDither (element, src, band_mask, levels, dither tech, dither_param) 
XiePhotoElement *element; 
XiePhototag src; 
unsigned int band_mask; 
XieLevels levels; 
XieDitherTechnique dither_tech; 
XiePointer dither_param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
band_mask Specifies which bands are to be operated on. 
levels Specifies the number of levels desired in the output 
data. 
dither tech Specifies the desired dither technique. 
dither param Specifies the list of additional parameters required by 
dither tech. 
Description 


The Dither element is used to reduce the number of quantization levels in an 
image. It accomplishes this by affecting adjacent pixels (area affect) to make up 
for the lack of depth resolution. 


Only bands selected by the band _mask are subject to processing. Other bands 
present in the image are passed through to the output. For example, a 
band_mask of 0012 indicates that only the “least significant band” would be 
processed; operating on all bands requires a band mask of 1112. Using 
band_mask to select source data that have two (2) or less levels is not permitted. 


The source data must be constrained. 


Dither techniques define the technique that can be used to dither an image. One 
of the following standard dither technique values can be assigned to dither tech: 


xieValDitherDefault 
xieValDitherErrorDiffusion 
xieValDitherOrdered 


If a vendor defined additional private dither techniques, the private technique 
values given to these techniques can be assigned to dither tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Output Attributes 
Class same aS src 
Type constrained 
Width same as src 
Height same as src 
Levels levels 
Structures 


XieFloDither sets the XiePhotoElement structure field elemType to 
xieElemDither, which identifies the element as a Dither, and sets the fields of the 
member structure Dither using the arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef unsigned long XieLevels[3]; 
typedef unsigned XieDitherTechnique; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieLevels levels; 
unsigned int band_mask; 
XieDitherTechnique dither_tech; 
XiePointer dither_ param; 

} Dither; 


} data; 
} XiePhotoElement; 


/* Definitions for DitherTechniques */ 


#define xieValDitherDefault 0 
#define xieValDitherErrorDiffusion 2 
#define xieValDitherOrdered 4 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDomain Invalid domain 
xieErrNoFloMatch Unconstrained src data or 
selected source data are bitonal 
xieErrNoFloSource Invalid src 
xieErrNoFloTechnique Invalid dither tech or dither param 
xieErrNoFloValue Invalid output levels: less than two or greater than src 
levels 
See Also 


XieTecDitherOrdered 


XIElib - Photoflo Element Functions XieFloGeometry 


Name 


XieFloGeometry - specify a Geometry element and set its parameters 


Syntax 


void XieFloGeometry (element, src, width, height, coefficients, constant, 
band_mask, sample_tech, sample_param) 
XiePhotoElement *element; 


XiePhototag src; 

unsigned int width; 
unsigned int height; 
float coefficients[6]; 


XieConstant constant; 

unsigned int band_mask; 
XieGeometryTechnique sample_tech; 
XiePointer sample_param; 


Arguments 


element 
src 

width 
height 
coefficients 


constant 


band_mask 
sample_tech 


sample param 


Description 


Specifies the XiePhotoElement structure to use. 
Specifies the element supplying source data. 

Specifies the horizontal dimension of the output data. 
Specifies the vertical dimension of the output data. 
Specifies an affine transformation to be applied to pixels 
insrc. 

Specifies the fill value used for output pixels that do not 
map back to a src pixel. 

Specifies which bands are to be operated on. 

Specifies the technique to be used for retrospectively 
resampling src. 

Specifies the list of additional parameters required by 
sample _tech. 


A Geometry element is used to perform geometric transformations on image 
data. Linear geometric resampling operations are implemented, such as: crop, 
mirror, scale, shear, rotate, translate, and combinations thereof. 


A Geometry element can be visualized as stepping through each possible output 
pixel location in turn and computing the location from which to obtain each input 
pixel value. Each pixel (x',y') in the output image is mapped to the coordinate 


location (x,y) in src by: 


The coordinate mapping coefficients (a,b,c,d,tx,ty), together with the output 
width and height, fully specify the geometric transformation. The following 
briefly (and approximately) summarizes the intuitive role of each parameter: 


a,d Scaling parameters. Increasing a and d will make the output image 
appear smaller, whereas decreasing them will make the output pixels 
appear larger. 

b,c Rotation/skew parameters. If b and c are zero, the output image will 
be a rectangular scaling of the input image. If a and d are both zero, 
b is one, and c is negative one, the image will appear rotated. The 
magnitude of b and c will affect scaling as well if a and d are zero. If 
more than two of (a,b,c,d) are nonzero, the effect is complicated. The 
image may appear skewed and scaled. 

tx, ty Translation parameters. Used to specify the offset between input and 
output coordinate systems. 

width, height These specify the output image dimensions of the selected 
band(s). Note that increasing the output image height and width over 
the input image size will not by itself cause magnification ifaandd 
are one (1) and b and c are zero (0), the output image will have the 
same appearance as the input, except that the borders will shrink or 
expand (as determined by width and height) and new areas of the 
image will be filled with constant. 


The region to be cropped in the input image is implicitly defined by the 
dimensions of the output image and the mapping from output to input 
coordinates. Depending on the size of the input and output images, the amount 
of scaling specified, and the amount of translation in the mapping, pixels in the 
output image may map off the edge of the input image and the constant value is 
used. 


Trichromatic image bands can be operated individually, all together, or in any 
combination, using band_mask. Since applying the same (a,b,c,d,tx,ty) mapping 
to inputs with diverse sizes will specify different transformations, operating on 
all bands in unison (band_mask of 1112) is most appropriate if the dimensions of 
all bands are equal. 


Often a given output pixel location (x’,y’) will not correspond exactly to a single 
pixel in the input image. The sample _tech technique is used to determine how 
the input data will be interpolated to produce each output pixel value. One of the 
following standard geometry technique values can be assigned to sample_tech: 


xieValGeom Default 
xieValGeomAntialias 
xieValGeomAntialiasByArea 
xieValGeomAntialiasByLPF 
xieValGeomBilinearInterp 
xieValGeomGaussian 

xieValGeom NearestNeighbor 


If a vendor defined additional private geometry techniques, the private 
technique values given to these techniques can be assigned to sample_tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Output Attributes 


Class same aS src 


Type same as src 

Width width 

Height height 

Levels same as src 
Structures 


XieFloGeometry sets the XiePhotoElement structure field elemType to 
xieElemGeometry, which identifies the element as a Geometry, and sets the fields 
of the member structure Geometry using the arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef float XieConstant[3]; 
typedef unsigned XieGeometryTechnique; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
unsigned int width; 
unsigned int height; 
float coefficients[6]; 
XieConstant constant; 
unsigned int band_mask; 
XieGeometryTechnique sample tech; 
XiePointer sample param; 
} Geometry; 


} data; 
} XiePhotoElement; 


/* Definitions for GeometryTechniques */ 
#define xieValGeomDefault 

#define xieValGeomAntialias 

#define xieValGeomAntialiasByArea 
#define xieValGeomAntialiasByLPF 
#define xieValGeomBilinearInterp 
#define xieValGeomGaussian 

#define xieValGeomNearestNeighbor 


PRPODRNO 


NO 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloSource Invalid src 

xieErrNoFloTechnique Invalid sample_tech or sample param 
xieErrNoFloValue Invalid coefficients 


See Also 


XieTecGeomAntialiasByArea, XieTecGeomAntialiasByLowpass, 
XieTecGeomGaussian, XieTecGeomNearestNeighbor 


XIElib - Photoflo Element Functions XieFloLogical 


Name 


XieFloLogical - specify a Logical element and set its parameters 
Syntax 


void XieFloLogical (element, src1, src2, domain, constant, operator, band_mask) 
XiePhotoElement *element; 
XiePhototag src1; 
XiePhototag src2; 
XieProcessDomain *domain; 
XieConstant constant; 
unsigned long operator; 
unsigned int band_mask; 


Arguments 

element Specifies the XiePhotoElement structure to use. 

srcl Specifies the first data source. 

src2 Specifies the second data source. 

domain Specifies the subset of source data that will be operated 

on. 

constant Specifies the constant data source. 

operator Specifies the logical operator to be used. 

band_mask Specifies which bands are to be operated on. 
Description 


A Logical element performs per-pixel bitwise operations on a single data source, 
or between two data sources, or between a single data source and a constant. 


When two sources are involved, srci1 and src2 are the phototags of the elements 
supplying source data; constant is ignored. A phototag is the position or index of 
an element within an array of elements used to specify a photoflo; the first 
element in the array has a phototag value of one (1). If the operation is to involve 
a constant, srci is one operand, src2 must be zero, and constant is used as the 
other operand. 


In order to specify a subset of source data that will be operated on, the phototag, 
offset_x, and offset_y fields of the XieProcessDomain structure pointed to by 
domain must be supplied; XIElib does not provide a convenience function to 
create and/or fill in an XieProcessDomain structure. If the entire source data is 
to be operated on, a pointer to an XieProcessDomain structure must still be 
provided, with the phototag field set to zero (0); the offset_x and offset _y fields 
are ignored. 


The value of operator matches the GC-function values defined by the core 


protocol specification for CreateGC. The output of a Logical element is 
determined by the number of data sources and operator: 


GC function dyadic operation 


Le on 
[Xor | constantXORsrol__| __sro2XORsrcl——_—*s 
[or constant OR set" "ste OR sre“ 


(NOT constant) AND (NOT $002 OR Ste) or src2) AND (NOT 
src1) src1) 


Nand (NOT constant) OR (NOT (NOT src2) OR (NOT 
src1) src1) 


Only bands selected by the band _mask are subject to processing. Other bands 
present in the image are passed through to the output. For example, a 
band_mask of 0012 indicates that only the “least significant band” would be 
processed; operating on all bands requires a band mask of 1112. 


Output Attributes 
Class same as srcl 
Type constrained 
Width same as srcl 
Height same as srcl 
Levels same as srcl 
Structures 


XieFloLogical sets the XiePhotoElement structure field elemType to 
xieElemLogical, which identifies the element as a Logical, and sets the fields of 
the member structure Logical using the arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef float XieConstant[3]; 
typedef struct { 

int offset_x; 

int offset _y; 

XiePhototag phototag; 
} XieProcessDomain; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src1; 
XiePhototag src2; 


XieProcessDomain domain; 
XieConstant constant; 

int operator; 

unsigned int band_mask; 


} Logical; 
} data; 
} XiePhotoElement; 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDomain Invalid domain 
xieErrNoFloMatch Class or levels differ between src1 and src2, or 


levels is not a power of 2, or 

srcl or src2 in not constrained 
xieErrNoFloOperator Invalid operator 
xieErrNoFloSource Invalid src1 or src2 


XIElib - Photoflo Element Functions XieFloMatchHistogram 


Name 


XieFloMatchHistogram - specify a MatchHistogram element and set its 
parameters 


Syntax 


void XieFloMatchHistogram (element, src, domain, shape, shape_param) 
XiePhotoElement *element; 
XiePhototag src; 
XieProcessDomain *domain; 
XieHistogramShape shape; 
XiePointer shape param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
domain Specifies the subset of source data that will be operated 
on. 
shape Specifies the form of the desired output data histogram. 
shape param Specifies the list of additional parameters required by 
shape. 
Description 


A MatchHistogram element produces output data that differ from the source 
data in terms of its pixel value distribution, or histogram. It allows the client to 
specify the desired shape of the resulting data's histogram (algorithmic 
description of resulting histogram shape). 


The source data must be constrained and single band, and it must have three or 
more levels. 


In order to specify a subset of source data that will be operated on, the phototag, 
offset_x, and offset_y fields of the XieProcessDomain structure pointed to by 
domain must be supplied; XIElib does not provide a convenience function to 
create and/or fill in an XieProcessDomain structure. Only data that intersects 
with the subset specified by domain is included in the histogram, and only that 
data will be affected in the result of the histogram matching operation: all other 
data will pass through unchanged. If the entire source data is to be operated on, 
a pointer to an XieProcessDomain structure must still be provided, with the 
phototag field set to zero (0); the offset_x and offset _y fields are ignored. 


HistogramShape defines the various match-histogram shape techniques that can 
be requested by a MatchHistogram element. One of the following standard 
match-histogram shape technique values can be assigned to shape: 


xieValHistogramFlat 
xieValHistogramGaussian 
xieValHistogramHyperbolic 


If a vendor defined additional private match-histogram shape techniques, the 
private technique values given to these techniques can be assigned to shape. 


Output Attributes 
Class single band 
Type constrained 
Width same as src 
Height same as src 
Levels same as src 
Structures 


XieFloMatchHistogram sets the XiePhotoElement structure field elemType to 
xieElemMatchHistogram, which identifies the element as a MatchHistogram, 
and sets the fields of the member structure MatchHistogram using the 
arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef unsigned XieHistogramShape; 
typedef struct { 

int offset_x; 

int offset _y; 

XiePhototag phototag; 
} XieProcessDomain; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieProcessDomain domain; 
XieHistogramShape shape; 
XiePointer shape param; 

} MatchHistogram; 


} data; 
} XiePhotoElement; 


/* Definitions for GeometryTechniques */ 
#define xieValGeomDefault 

#define xieValGeomAntialias 

#define xieValGeomAntialiasByArea 
#define xieValGeomAntialiasByLPF 
#define xieValGeomBilinearInterp 
#define xieValGeomGaussian 

#define xieValGeomNearestNeighbor 


PrRPODFRNO 


NO 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDomain Invalid domain 

xieErrNoFloMatch Invalid src data: unconstrained, triple band, or bitonal 
xieErrNoFloSource Invalid src 

xieErrNoFloTechnique Invalid shape or shape_param 


See Also 


XieTecHistogramGaussian, XieTecHistogramHyperbolic 


XIElib - Photoflo Element Functions XieFloMath 


Name 


XieFloMath - specify a Math element and set its parameters 
Syntax 


void XieFloMath (element, src, domain, operator, band_mask) 
XiePhotoElement *element; 
XiePhototag src; 
XieProcessDomain *domain; 
XieMathOp operator; 
unsigned int band_mask; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
domain Specifies the subset of source data that will be operated 
on. 
operator Specifies the mathematical operation to be applied. 
band_mask Specifies which bands are to be operated on. 
Description 


A Math element applies a single operand mathematical operation to the source 
data on a point-wise basis. 


In order to specify a subset of source data that will be operated on, the phototag, 
offset_x, and offset_y fields of the XieProcessDomain structure pointed to by 
domain must be supplied; XIElib does not provide a convenience function to 
create and/or fill in an XieProcessDomain structure. If the entire source data is 
to be operated on, a pointer to an XieProcessDomain structure must still be 
provided, with the phototag field set to zero (0); the offset_x and offset_y fields 
are ignored. 


Pixel computations that would lead to errors will yield valid server-dependent 
values (for example, the log of a constrained pixel value of zero might result in a 
value of zero). Only bands selected by the band mask are subject to processing. 
Other bands present in the image are passed through to the output. For 
example, a band_mask of 0012 indicates that only the “least significant band” 
would be processed; operating on all bands requires a band mask of 1112. Using 
band_mask to select source data that have two (2) or less levels is not permitted. 


The following valid mathematical operations that can be invoked through the 
Math element: 


| Operator | Meaning 
xieValExp 


natural logarithm 
xieValLog2 logarithm base 2 


xieValLog10 logarithm base 10 
xieValSquare 


sieValSart 


All output data attributes are inherited from the source data. 


Output Attributes 
Class same as src 
Type same as src 
Width same as src 
Height same as src 
Levels same as src 
Structures 


XieFloMath sets the XiePhotoElement structure field elemType to xieElemMath, 
which identifies the element as a Math, and sets the fields of the member 
structure Math using the arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef unsigned XieMathOp; 
typedef struct { 

int offset x; 

int offset _y; 

XiePhototag phototag; 
} XieProcessDomain; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieProcessDomain domain; 
XieMathOp operator; 
unsigned int band_mask; 

} Math; 


} data; 
} XiePhotoElement; 


/* Definitions of Math Operators */ 
#define xieValExp 

#define xieValLn 

#define xieValLog2 

#define xieValLog10 

#define xieValSquare 

#define xieValSqrt 


ANU PWNF 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDomain Invalid domain 

xieErrNoFloMatch Selected source data are bitonal 
xieErrNoFloSource Invalid src 


xieErrNoFloOperator Invalid operator 


XIElib - Photoflo Element Functions XieFloPasteUp 


Name 


XieFloPasteUp - specify a PasteUp element and set its parameters 
Syntax 


void XieFloPasteUp (element, width, height, constant, tiles, tile count) 
XiePhotoElement *element; 
unsigned int width; 
unsigned int height; 
XieConstant constant; 
XieTile *tiles 
unsigned int tile count; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
width Specifies the full horizontal extent of the output data. 
height Specifies the full vertical extent of the output data. 
constant Specifies the fill value for output regions that do not 
intersect the regions defined in tiles. 
tiles Specifies a list of tile descriptors. 
tile count Specifies the number of tile descriptors in tiles. 
Description 


A PasteUp element is an N-input translate operation that outputs data 
constructed from various source data tiles or a constant value. 


Each of the tiles specifies a src (the phototag of the element supplying source 
data), and the coordinates, dst x and dst _y, where the tile belongs in the output 
data. A phototag is the position or index of an element within an array of 
elements used to specify a photoflo; the first element in the array has a phototag 
value of one (1). 


Each region of the output data is defined by a tile's destination coordinates, 


dst _x and dst _y, and its src dimensions. For output regions where no tile provides 
input, the value of constant is used. If tiles overlap, a stacking-order rule defines 

which pixel value will be output: the last tile involved in the overlap in the list of 

tiles will provide the output pixel. 


At least one tile must be supplied. Except for width and height, all attributes of 
each source tile must match. In addition, for triple band input, inter-band 
dimensions within each tiles must match. 


Output Attributes 
Class same as tiles 
Type same as tiles 


Width width 


Height height 
Levels same as tiles 


Structures 


XieFloPasteUp sets the XiePhotoElement structure field elemType to 
xieElemPasteUp, which identifies the element as a PasteUp, and sets the fields of 
the member structure PasteUp using the arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef float XieConstant[3]; 
typedef struct { 

XiePhototag src; 

int dst_x; 

int dst _y; 
} XieTile; 


typedef struct { 
int elemType; 
union { 


struct { 
unsigned int width; 
unsigned int height; 
XieConstant constant; 
XieTile *tiles; 
unsigned int tile count; 


} PasteUp; 
} data; 
} XiePhotoElement; 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloMatch Incompatible attributes between tiles or 
unequal inter-band dimensions within a tile 
xieErrNoFloSource Invalid source tiles or 
no tiles were specified 
See Also 


XieFreePasteUpTiles 


XIElib - Photoflo Element Functions XieFloPoint 


Name 


XieFloPoint - specify a Point element and set its parameters 
Syntax 


void XieFloPoint (element, src, domain, lut, band_mask) 
XiePhotoElement *element; 
XiePhototag src; 
XieProcessDomain *domain; 
XieLut lut; 
unsigned int band_mask; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
domain Specifies the subset of source data that will be operated 
on. 
lut Specifies the LUT resource supplying the lookup table. 
band_mask Specifies which bands are to be operated on. 
Description 


A Point element maps source pixel values to output pixel values using a lookup 
table (LUT). 


src is the phototag of the element supplying constrained source data. A phototag 
is the position or index of an element within an array of elements used to specify 
a photoflo; the first element in the array has a phototag value of one (1). Lut is 
the phototag of the ImportClientLUT or ImportLUT element supplying the lookup 
table data. 


In order to specify a subset of source data that will be operated on, the phototag, 
offset_x, and offset_y fields of the XieProcessDomain structure pointed to by 
domain must be supplied; XIElib does not provide a convenience function to 
create and/or fill in an XieProcessDomain structure. If the entire source data is 
to be operated on, a pointer to an XieProcessDomain structure must still be 
provided, with the phototag field set to zero (0); the offset_x and offset _y fields 
are ignored. 


band_mask specifies which bands are to be operated on (all bands must be 
specified if lut is single band and src is triple band). For example, a band_mask 
of 0012 indicates that only the “least significant band” would be processed; 
operating on all bands requires a band_mask of 1112. 


The output is constrained, with the width and height taken from src and class 
and levels taken from Jut. When src is single band and lut is triple band, for the 
bands that are indicated by band mask, the output bands are remapped through 
their respective lut bands, whereas the other bands are just replications of the 


single src band. If domain is used, the class and levels of ut must match those of 
src. 


Each lut array must contain sufficient entries so that all potential pixel values 
found in src can form a valid index into the array. Generally each src pixel value 
is used directly as an index into a Jut array. When triple band src data are 
remapped through a single band lut, however, pixel values from all three src 
bands are combined to form an array index; for this case, width and height must 
match for all bands. 


When a single band lut is used to remap triple band src data, the following 
presents the algorithm for computing combined array indices: 


LUT band LUT indexing algorithm for combining pixel values 

order 

LSFirst index = value[0] + value[1] x levels[O] + value[2] x 
levels[0] x levels[1] 


MSFirst index = value[2] + value[1] x levels[2] + value[0] x 
levels[2] x levels[1] 


Output Attributes 
Class same as lut 
Type constrained 
Width same as src 
Height same as src 
Levels same as lut 
Structures 


XieFloPoint sets the XiePhotoElement structure field elemType to xieElemPoint, 
which identifies the element as a Point, and sets the fields of the member 
structure Point using the arguments in the argument list. 


typedef XID XieLut; 
typedef unsigned XiePhototag; 
typedef struct { 
int offset_x; 
int offset _y; 
XiePhototag phototag; 
} XieProcessDomain; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieProcessDomain domain; 
XieLut lut; 
unsigned int band_mask; 

} Point; 


} data; 
} XiePhotoElement; 


Errors 


xieErrNoFloAlloc 
xieErrNoFloDomain 
xieErrNoFloMatch 


xieErrNoFloSource 


See Also 


Insufficient resources (for example, memory) 

Invalid domain 

Unconstrained src data, or 

lut does not contain enough entries, or 

lut is single band and src is triple band, but band_mask 
is incomplete, or 

domain is being used, but lut class or levels do not 
match those of src 

Invalid sre or lut 


XieFloImportLUT, XieFloImportClientLUT 


XIElib - Photoflo Element Functions XieFloUnconstrain 


Name 
XieFloUnconstrain - specify an unconstrain element and set its parameters 
Syntax 


void XieFloUnconstrain (element, src) 
XiePhotoElement *element; 
XiePhototag src; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying constrained source 
data. 
Description 


An Unconstrain element produces unconstrained output data from constrained 
input data. 


Output Attributes 
Class same aS src 
Type unconstrained 
Width same as src 
Height same as src 
Levels unknown 
Structures 


XieFloUnconstrain sets the XiePhotoElement structure field elemType to 
xieElemUnconstrain, which identifies the element as an Unconstrain, and sets 
the fields of the member structure Unconstrain using the arguments in the 
argument list. 


typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
} Unconstrain; 


} data; 
} XiePhotoElement; 


Errors 


xieErrNoFloAlloc 
xieErrNoFloMatch 
xieErrNoFloSource 


See Also 


XieFloConstrain 


Insufficient resources (for example, memory) 
Unconstrained src data 
Invalid src 


XIElib - Photoflo Element 
Functions XieFloExportClientHistogram 


Name 


XieFloExportClientHistogram - specify an ExportClientHistogram element and 
set its parameters 


Syntax 


void XieFloExportClientHistogram (element, src, domain, notify) 
XiePhotoElement *element; 
XiePhototag src; 
XieProcessDomain *domain; 
XieExportNotify notify; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying single band constrained 
source data. 
domain Specifies the subset of the source data from which the 
distribution will be generated. 
notify Specifies whether to enable sending an ExportAvailable 
event. 
Description 


An ExportClientHistogram element generates a histogram of the pixel values 
found in the source data. It prepares histogram data that can be retrieved by the 
client using XieGetClientData. An event can be requested that will notify the 
client when histogram data becomes available. 


The data generated for the client is a list of XieHistogramData where each entry 
consists of a value (that is, a pixel value) followed by the count of pixels found 
with that value. If the number of pixels for a given value exceeds the capacity of 
count, that count will be returned at the maximum value (that is, 232 - 1). Pixel 
values that are not found in the data are not included in the histogram data: no 
entries are returned where count is zero. 


In order to specify a subset of source data that will be operated on, the phototag, 
offset_x, and offset_y fields of the XieProcessDomain structure pointed to by 
domain must be supplied; XIElib does not provide a convenience function to 
create and/or fill in an XieProcessDomain structure. Only data that intersects 
with the subset specified by domain is included in the histogram. If the entire 
source data is to be operated on, a pointer to an XieProcessDomain structure 
must still be provided, with the phototag field set to zero (0); the offset x and 
offset_y fields are ignored. 


One of three standard export notify values can be assigned to notify: 


xieValDisable 
xieValFirstData 


xieValNewData 


If notify was specified as xieValFirstData, this event will be sent only the first 
time data become available; otherwise, if xieValNewData was specified, this 
event will be generated each time the amount of data available changes from 
zero to nonzero. 


Structures 


XieFloExportClientHistogram sets the XiePhotoElement structure field elemType 
to xieElemExportClientHistogram, which identifies the element as an 
ExportClientHistogram, and sets the fields of the member structure 
ExportClientHistogram using the arguments in the argument list. 


typedef unsigned XieExportNotify; 
typedef unsigned XiePhototag; 
typedef struct { 
int offset _x; 
int offset _y; 
XiePhototag phototag; 
} XieProcessDomain; 
typedef struct { 
unsigned long value; 
unsigned long count; 
} XieHistogramData; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieProcessDomain domain; 
XieExportNotify notify; 

} ExportClientHistogram; 


} data; 
} XiePhotoElement; 


/* Definitions of ExportNotify */ 


#define xieValDisable 1 
#define xieValFirstData 2 
#define xieValNewData 3 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDomain Invalid domain 
xieErrNoFloMatch Unconstrained src data or 
triple band src data 
xieErrNoFloSource Invalid src 
xieErrNoFloValue Invalid notify 


See Also 


XieGetClientData 


XIElib - Photoflo Element Functions Xie FloExportClientLUT 


Name 
XieFloExportClientLUT - specify an ExportClientLUT element and set its 
parameters 
Syntax 


void XieFloExportClientLUT (element, src, band_order, notify, start, length) 
XiePhotoElement *element; 
XiePhototag src; 
XieOrientation band _ order; 
XieExportNotify notify; 


XieLTriplet start; 
XieLTriplet length; 
Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying lookup table data. 
band _order Specifies the order of triple band arrays. 
notify Specifies whether to enable sending an ExportAvailable 
event. 
start Specifies the index of the first array entry that should 
be returned. 
length Specifies the number of array entries that should be 
returned. 
Description 


An ExportClientLUT element allows data imported from an ImportLUT or an 
ImportClientLUT element to be retrieved by the client. The actual transport of 
lookup table data through the protocol stream is requested using 
XieGetClientData. 


One of three standard export notify values can be assigned to notify: 


xieValDisable 
xieValFirstData 
xieValNewData 


If notify was specified as xieValFirstData, this event will be sent only the first 
time data become available; otherwise, if xieValNewData was specified, this 
event will be generated each time the amount of data available changes from 
zero to nonzero. 


band _ order is the order in which triple band arrays are transmitted through the 
protocol stream. One of the following standard orientation values can be 
assigned to band order: 


xieValLS First 
xieValMS First 


The least significant band of trichromatic data is the first band mentioned in the 
common name of the colorspace: for example, red is the least significant band of 
RGB data. For band-by-plane data, band_order specifies whether this band 
corresponds with the least significant or most significant LUT array. Each array 
is transported as a separate data stream: 


[band | LSFirst MSFirst 


R7Re R5R4 R3R2R1Ro B7B6B 5B4B3B 2B1Bo 


G7 GeGsG4G3G2 GiGo G7 GeGsG4G3G2 GiGo 
B7BeB 5B4B3B 2B1Bo R7Rs RsR4 R3R2R1Ro 


The size of each array entry is either 1, 2, or 4 bytes: the smallest size into which 
the output quantization levels can be stored. When array entries require multiple 
bytes, the byte order per entry is determined in the same manner as other 
numeric data: it is the byte orientation established at core X connection setup 
time. 


Structures 


XieFloExportClientLUT sets the XiePhotoElement structure field elemType to 
xieElemExportClientLUT, which identifies the element as an ExportClientLUT, 
and sets the fields of the member structure ExportClientLUT using the 
arguments in the argument list. 


typedef unsigned XieExportNotify; 
typedef unsigned XieOrientation; 
typedef unsigned long XieLTriplet[3]; 
typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieOrientation band_order; 
XieExportNotify notify; 
XieLTriplet start; 
XieLTriplet length; 

} ExportClientLUT; 


} data; 
} XiePhotoElement; 


/* Definitions of ExportNotify */ 
#define xieValDisable 

#define xieValFirstData 
#define xieValNewData 
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/* Definitions of Orientation Types */ 
#define xieValLSFirst 1 
#define xieValMSFirst 2 


Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloMatch start + length exceeds number of entries in an array 
xieErrNoFloSource Invalid src 
xieErrNoFloValue Invalid notify or band_ order 

See Also 


XieFloImportLUT, XieFloImportClientLUT, XieGetClientData 


XIElib - Photoflo Element Functions Xie FlOExportClientPhoto 


Name 


XieFloExportClientPhoto - specify an ExportClientPhoto element and set its 
parameters 


Syntax 


void XieFloExportClientPhoto (element, src, notify, encode _tech, encode_param) 
XiePhotoElement *element; 
XiePhototag src; 
XieExportNotify notify; 
XieEncodeTechnique encode _ tech; 
XiePointer encode_ param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying constrained data. 
notify Specifies whether to enable sending an ExportAvailable 
event. 
encode tech Specifies the technique to compress or format the 
exported data. 
encode_ param Specifies the list of additional parameters required by 
encode _tech. 
Description 


An ExportClientPhoto element makes image data available to the protocol 
stream. The attributes of the exported data are determined by the attributes of 
the source data. The format of the data is specified by the encode_tech 
technique and encode_param. The actual transport of image data through the 
protocol stream is requested using XieGetClientData. 


One of three standard export notify values can be assigned to notify: 


xieValDisable 
xieValFirstData 
xieValNewData 


If notify was specified as xieValFirstData, this event will be sent only the first 
time data become available; otherwise, if xieValNewData was specified, this 
event will be generated each time the amount of data available changes from 
zero to nonzero. 


Encode techniques define the techniques that can be used to compress an image 
or format it as uncompressed data. One of the following standard encode 
technique values can be assigned to encode _tech: 


xieValEncodeServerChoice 
xieValEncodeUncompressedSingle 
xieValEncodeUncompressedTriple 


xieValEncodeG31D 
xieValEncodeG32D 
xieValEncodeG42D 
xieValEncodeJPEGBaseline 
xieValEncodeJPEGLossless 
xieValEncodeTIFF2 
xieValEncodeTIFFPackBits 


If a vendor defined additional private encode techniques, the private technique 
values given to these techniques can be assigned to encode _tech. 


Structures 


XieFloExportClientPhoto sets the XiePhotoElement structure field elemType to 
xieElemExportClientPhoto, which identifies the element as an 
ExportClientPhoto, and sets the fields of the member structure 
ExportClientPhoto using the arguments in the argument list. 


typedef unsigned XieExportNotify; 
typedef unsigned XiePhototag; 
typedef unsigned XieEncodeTechnique; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieExportNotify notify; 
XieEncodeTechnique encode tech; 
XiePointer encode param; 

} ExportClientPhoto; 


} data; 
} XiePhotoElement; 


/* Definitions of ExportNotify */ 
#define xieValDisable 

#define xieValFirstData 
#define xieValNewData 
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/* Definitions for EncodeTechniques */ 
#define xieValEncodeServerChoice 
#define xieValEncodeUncompressedSingle 
#define xieValEncodeUncompressedTriple 
#define xieValEncodeG31D 

#define xieValEncodeG32D 

#define xieValEncodeG42D 

#define xieValEncodeJPEGBaseline 10 
#define xieValEncodeJPEGLossless 12 
#define xieValEncodeTIFF2 14 
#define xieValEncodeTIFFPackBits 16 


Errors 
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xieErrNoFloAlloc Insufficient resources (for example, memory) 


xieErrNoFloMatch Unconstrained src data 


xieErrNoFloSource Invalid src 
xieErrNoFloTechnique Invalid encode tech or encode param 
xieErrNoFloValue Invalid notify 

See Also 


XieGetClientData, XieFloExportClientPhoto, 
XieTecEncodeUncompressedSingle, XieTecEncodeUncompressedTriple, 
XieTecEncodeG31D, XieTecEncodeG32D, XieTecEncodeG42D, 
XieTecEncodeServerChoice, XieTecEncodeJPEGBaseline, 
XieTecEncodeJPEGLossless, XieTecEncodeTIFF2, XieTecEncodeTIFFPackBits 


XIElib - Photoflo Element Functions XieFloExportClientROI 


Name 


XieFloExportClientROI - specify an ExportClientROI element and set its 
parameters 


Syntax 


void XieFloExportClientROI (element, src, notify) 
XiePhotoElement *element; 
XiePhototag src; 
XieExportNotify notify; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying the list-of-rectangles. 
notify Specifies whether to enable sending an ExportAvailable 
event. 
Description 


An ExportClientROI element allows a list-of-rectangles, imported using an 
ImportROI or an ImportClientROI element, to be retrieved by the client. The 
actual transport of list-of-rectangles data through the protocol stream is 
requested using a GetClientData element. 


One of three standard export notify values can be assigned to notify: 


xieValDisable 
xieValFirstData 
xieValNewData 


If notify was specified as xieValFirstData, this event will be sent only the first 
time data become available; otherwise, if xieValNewData was specified, this 
event will be generated each time the amount of data available changes from 
zero to nonzero. 


Structures 


XieFloExportClientROI sets the XiePhotoElement structure field elemType to 
xieElemExportClientROI, which identifies the element as an ExportClientROI, 
and sets the fields of the member structure ExportClientROI using the 
arguments in the argument list. 


typedef unsigned XieExportNotify; 
typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieExportNotify notify; 
} ExportClientROI; 


} data; 
} XiePhotoElement; 


/* Definitions of ExportNotify */ 
#define xieValDisable 

#define xieValFirstData 
#define xieValNewData 
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Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloSource Invalid src 
xieErrNoFloValue Invalid notify 


See Also 
XieFloImportROI, XieFloImportClientROI, XieGetClientData 


XIElib - Photoflo Element Functions Xie FloExportDrawable 


Name 


XieFloExportDrawable - specify an ExportDrawable element and set its 
parameters 


Syntax 


void XieFloExportDrawable (element, src, drawable, gc, dst_x, dst_y) 
XiePhotoElement *element; 
XiePhototag src; 
Drawable drawable; 


GC gc; 
int dst_x; 
int dst_y; 
Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying constrained source 
data. 
drawable Specifies the Window or Pixmap into which the data will 
be written. 
gc Specifies the GContext to be used when transferring 
pixels to drawable. 
dst_x Specifies where the data should be placed in drawable. 
dst _y Specifies where the data should be placed in drawable. 
Description 


An ExportDrawable element allows Colormap index data to be exported to a 
Window or Pixmap. 


The following components are used from gc: function, plane-mask, subwindow- 
mode, clip-x-origin, clip-y-origin, and clip-mask. 


The levels of src must exactly match the depth of drawable and gc (that is, 
levels must be 2depth). 
Structures 


XieFloExportDrawable sets the XiePhotoElement structure field elemType to 
xieElemExportDrawable, which identifies the element as an ExportDrawable, 
and sets the fields of the member structure ExportDrawable using the 
arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef struct { 
int elemType; 


union { 


struct { 


XiePhototag src; 
Drawable drawable; 


GC gc; 
int dst_x; 
int dst _y; 
} ExportDrawable; 
} data; 
} XiePhotoElement; 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDrawable Invalid drawable 
xieErrNoFloGC Invalid gc 
xieErrNoFloMatch Invalid src data: triple band, unconstrained, levels does 
not match depth 
xieErrNoFloSource Invalid src 
See Also 


XieFIloExportDrawablePlane 


XIElib - Photoflo Element 
Functions XieFloExportDrawablePlane 


Name 


XieFloExportDrawablePlane - specify an ExportDrawablePlane element and set 
its parameters 


Syntax 


void XieFloExportDrawablePlane (element, src, drawable, gc, dst_x, dst_y) 
XiePhotoElement *element; 
XiePhototag src; 
Drawable drawable; 


GC gc; 
int dst_x; 
int dst _y; 
Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying constrained bitonal 
source data. 
drawable Specifies the Window or Pixmap into which the data will 
be written. 
gc Specifies the GContext to be used when transferring 
pixels to drawable. 
dst_x Specifies where the data should be placed in drawable. 
dst _y Specifies where the data should be placed in drawable. 
Description 


An ExportDrawablePlane element allows single-band single-bit (bitonal) data to 
be exported to a Window or a Pixmap. 


The following components are used from gc: function, plane-mask, foreground, 
background, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip- 
mask. For the fill-style component of gc, values of FillSolid and FillTiled are 
treated as synonyms for FillOpaqueStippled. 


Structures 


XieFloExportDrawablePlane sets the XiePhotoElement structure field elemType 
to xieElemExportDrawablePlane, which identifies the element as an 
ExportDrawablePlane, and sets the fields of the member structure 
ExportDrawablePlane using the arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef struct { 
int elemType; 


union { 


struct { 


XiePhototag src; 
Drawable drawable; 


GC gc; 
int dst_x; 
int dst _y; 
} ExportDrawablePlane; 
} data; 
} XiePhotoElement; 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloDrawable Invalid drawable 
xieErrNoFloGC Invalid gc 
xieErrNoFloMatch Invalid src data: triple band, not constrained, levels > 2 
xieErrNoFloSource Invalid src 
See Also 


XieFIloExportDrawable 


XIElib - Photoflo Element Functions XieFloExportLUT 


Name 
XieFloExportLUT - specify an ExportLUT element and set its parameters 
Syntax 


void XieFloExportLUT (element, src, lut, merge, start) 
XiePhotoElement *element; 
XiePhototag src; 


XieLut lut; 
Bool merge; 
XieLTriplet start; 
Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying lookup table data. 
lut Specifies the ID of the LUT to receive the data. 
merge Specifies how new array entries replace existing 
entries. 
start Specifies the index of the first array entry that should 
be written in lut, per band. 
Description 


An ExportLUT element allows data imported from an ImportLUT or 
ImportClientLUT element to be saved in an existing LUT resource. 


merge specifies that new array entries from src should replace entries that 

already exist within lut. If merge is False, start must be zero for each band. In 
this case, /ut will inherit the attributes of src and be populated with its data; the 
previous attributes and data of Jut are overwritten when the photoflo completes. 


If merge is True and lut has existing attributes, the data from src will replace the 


data from lut, beginning at position start. If merge is True,but lut has not yet 
been populated, it is an error. 


The attributes of src must match those of lut, and the combination of start and 
the length of src must specify a valid subrange existing within lut. 


Structures 


XieFloExportLUT sets the XiePhotoElement structure field elemType to 

xieElemExportLUT, which identifies the element as an ExportLUT, and sets the 
fields of the member structure ExportLUT using the arguments in the argument 
list. 


typedef XID XieLut; 
typedef unsigned long XieLTriplet[3]; 
typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 


union { 


struct { 
XiePhototag src; 
XieLut lut; 
Bool merge; 
XieLTriplet start; 
} ExportLUT; 


} data; 
} XiePhotoElement; 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloLUT Invalid lut 
xieErrNoFloMatch merge true and attributes do not match between src 
and lut, or 
merge true and start + src length is not a subrange of 
lut 
xieErrNoFloSource Invalid src 
xieErrNoFloValue merge false and start nonzero 
See Also 


XieFloImportLUT, XieFloImportClientLUT 


XIElib - Photoflo Element Functions XieFloExportPhotomap 


Name 


XieFloExportPhotomap - specify an ExportPhotomap element and set its 
parameters 


Syntax 


void XieFloExportPhotomap (element, src, photomap, encode _tech, 
encode_ param) 
XiePhotoElement *element; 
XiePhototag src; 
XiePhotomap photomap; 
XieEncodeTechnique encode _ tech; 
XiePointer encode_ param; 


Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying source data. 
photomap Specifies the ID of the photomap resource to receive the 
data. 
encode tech Specifies the image compression or formatting 
technique. 
encode param Specifies the list of additional parameters required by 
encode _tech. 
Description 


An ExportPhotomap element allows data from photoflo operations to be saved in 
a photomap. A photomap is a server resource that can be used to store image 
data. 


photomap will inherit the attributes of src and be populated with its data. The 
previous attributes and data of photomap are overwritten when the photoflo 
completes. 


Encode techniques define the techniques that can be used to compress an image 
or format it as uncompressed data. One of the following standard encode 
technique values can be assigned to encode _tech: 


xieValEncodeServerChoice 
xieValEncodeUncompressedSingle 
xieValEncodeUncompressedTriple 
xieValEncodeG31D 
xieValEncodeG32D 
xieValEncodeG42D 
xieValEncodeJPEGBaseline 
xieValEncodeJPEGLossless 
xieValEncodeTIFF2 
xieValEncodeTIFFPackBits 


If a vendor defined additional private encode techniques, the private technique 
values given to these techniques can be assigned to encode _tech. 


Structures 


XieFloExportPhotomap sets the XiePhotoElement structure field elemType to 
xieElemExportPhotomap, which identifies the element as an ExportPhotomap, 
and sets the fields of the member structure ExportPhotomap using the 
arguments in the argument list. 


typedef unsigned XiePhototag; 
typedef XID XiePhotomap; 
typedef unsigned XieEncodeTechnique; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XiePhotomap photomap; 
XieEncodeTechnique encode tech; 
XiePointer encode param; 

} ExportPhotomap; 


} data; 
} XiePhotoElement; 


/* Definitions for EncodeTechniques */ 

#define xieValEncodeServerChoice 1 
#define xieValEncodeUncompressedSingle 2 
#define xieValEncodeUncompressedTriple 3 
#define xieValEncodeG31D 4 
#define xieValEncodeG32D 6 


#define xieValEncodeG42D 8 
#define xieValEncodeJPEGBaseline 10 
#define xieValEncodeJPEGLossless 12 
#define xieValEncodeTIFF2 14 
#define xieValEncodeTIFFPackBits 16 
Errors 
xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloPhotomap Invalid photomap 
xieErrNoFloSource Invalid src 


xieErrNoFloTechnique Invalid encode tech or encode param 
See Also 


XieTecEncodeUncompressedSingle, XieTecEncodeUncompressedTriple, 
XieTecEncodeG31D, XieTecEncodeG32D, XieTecEncodeG42D, 
XieTecEncodeServerChoice, XieTecEncodeJPEGBaseline, XieTecEncodeTIFF2, 
XieTecEncodeTIFFPackBits 


XIElib - Photoflo Element Functions XieFloExportROI 


Name 
XieFloExportROI - specify an ExportROI element and set its parameters 
Syntax 


void XieFloExportROI (element, src, roi) 
XiePhotoElement *element; 
XiePhototag src; 


XieRoi roi; 
Arguments 
element Specifies the XiePhotoElement structure to use. 
src Specifies the element supplying a list-of-rectangles. 
roi Specifies the ID of the ROI resource to receive the data. 
Description 


An ExportROI element allows data imported from an ImportROI or 
ImportClientROI element to be saved in an existing Rectangles-Of- Interest (ROI) 
resource. 


roi will be populated with new data. The previous data of roi are overwritten 
after the photoflo completes. 


Structures 


XieFloExportROI sets the XiePhotoElement structure field elemType to 
xieElemExportROI, which identifies the element as an ExportROI, and sets the 
fields of the member structure ExportROI using the arguments in the argument 
list. 


typedef XID XieRoi; 
typedef unsigned XiePhototag; 


typedef struct { 
int elemType; 
union { 


struct { 
XiePhototag src; 
XieRoi roi; 

} ExportROI, 


} data; 
} XiePhotoElement; 
Errors 


xieErrNoFloAlloc Insufficient resources (for example, memory) 
xieErrNoFloROI Invalid roi 


xieErrNoFloSource Invalid src 


See Also 
XieFloImportROI, XieFloImportClientROI 


XIElib - Technique Functions XieTecColorAllocAll 


Name 


XieTecColorAllocAll - allocate and fill an XieColorAllocAllParam structure 


Syntax 
XieColorAllocAllParam *XieTecColorAllocAll (fill) 
unsigned long fill; 
Arguments 
fill Specifies thefill value to use for pixels which cannot be 
allocated. 
Returns 


The XieColorAllocAllParam structure. 
Description 


XieTecColorAllocAll allocates and returns a pointer to an XieColorAllocAllParam 
structure. The returned structure represents the list of parameters required by 
the AllocAll color allocation technique and may be used as the color alloc_param 
argument of XieFloConvertToIndex (when the color alloc tech argument is 
xieValColorAllocAll). 


If insufficient memory is available, XieTecColorAllocAll returns NULL. To free 
the memory allocated to this structure, use XFree. 


The AllocAll color allocation technique allocates a read-only Colormap cell for 
each new pixel found. If the Colormap runs out of cells, the remaining new pixels 
are mapped to fill. A ColorAlloc event, which warns the client that results are of 
lesser fidelity than desired, will be sent if it is necessary to use fill, and the client 
has requested it (see XieFloConvertToIndex). AllocAll is appropriate only for 
dynamic Colormaps and requires that the number of discrete image pixels fit 
within the size of the Colormap to avoid running out of cells. 


Structures 
XieTecColorAllocAll sets the structure field fill to the value of the argument fill. 
typedef struct { 


unsigned long fill; 
} XieColorAllocAllParam; 


See Also 
XieFloConvertToIndex 


XIElib - Technique Functions XieTecColorAllocMatch 


Name 
XieTecColorAllocMatch - allocate and fill an XieColorAllocMatchParam structure 
Syntax 


XieColorAllocMatchParam *XieTecColorAllocMatch (match limit, gray_limit) 
double match_limit; 
double gray limit; 


Arguments 

match_limit Specifies the color allocation control value. 

gray limit Specifies the gray scale allocation control value. 
Returns 


The XieColorAllocMatchParam structure. 
Description 


XieTecColorAllocMatch allocates and returns a pointer to an 
XieColorAllocMatchParam structure. The returned structure represents the list 
of parameters required by the AllocMatch color allocation technique and may be 
used as the color alloc_param argument of XieFloConvertToIndex (when the 
color_alloc_tech argument is xieValColorAllocMatch). 


If insufficient memory is available, XieTecColorAllocMatch returns NULL. To free 
the memory allocated to this structure, use XFree. 


The AllocMatch color allocation technique allows a trade-off between image 
fidelity and Colormap usage via a pair of granularity parameters. The highest 
priority is given to allocating read-only cells in a sequence that provides an even 
distribution of pixels throughout the colorspace. Secondary priority is given to 
the frequency of usage of image pixels. Any image pixel that is a close enough 
match to an existing read-only cell will share that cell (where “close” is 
determined by the granularity controls). For other image pixels, new read-only 
allocations are made. When no more cells are available, each remaining image 
pixel is matched to the closest read-only cell. The AllocMatch color allocation 
technique is appropriate for both static and dynamic Colormaps. For the sake of 
computational efficiency the number of discrete image pixels should not exceed 
the size of the Colormap. 


match_limit and gray_match control the allocation of colors and gray shades, 
respectively. The minimum value (0.0) specifies exact matches (within the limits 
of the Colormap). The maximum value (1.0) encompasses the entire colorspace 
within which no new cells are allocated. A ColorAlloc event, which warns the 
client that results are of lesser fidelity than desired, can be sent if the Colormap 
runs out of cells. 


Structures 


XieTecColorAllocMatch sets the structure field match limit to the value of the 
argument match _ limit; and the structure field gray limit to the value of the 
argument gray limit. 


typedef struct { 
float match _ limit; 
float gray_ limit; 
} XieColorAllocMatchParam; 


See Also 
XieFloConvertToIndex 


XIElib - Technique Functions XieTecColorAllocRequantize 


Name 


XieTecColorAllocRequantize - allocate and fill an XieColorAllocRequantizeParam 
structure 


Syntax 


XieColorAllocRequantizeParam *XieTecColorAllocRequantize (max _cells) 
unsigned long max _cells; 


Arguments 
max_cells Specifies the maximum number of Colormap allocations 
to allow. 
Returns 


The XieColorAllocRequantizeParam structure. 
Description 


XieTecColorAllocRequantize allocates and returns a pointer to an 
XieColorAllocRequantizeParam structure. The returned structure represents the 
list of parameters required by the AllocRequantize color allocation technique 
and may be used as the color alloc_param argument of XieFloConvertToIndex 
(when the color_alloc_tech argument is xieValColorAllocRequantize). 


If insufficient memory is available, XieTecColorAllocRequantize returns NULL. 
To free the memory allocated to this structure, use XFree. 


The AllocRequantize color allocation technique first reduces the total number of 
discrete pixel values in the image to be no more than a specified number and 
then allocates the resulting pixel values as read-only cells from the Colormap. 
One method of accomplishing this reduction process can be found in "Color 
image quantization for frame buffer display" (Heckbert, P. S., Comput. Graph. 16, 
3). 


If max_cells is zero or greater than the number of unallocated Colormap cells, 
the reduction algorithm will restrict its output to the number of free cells. A 
ColorAlloc event, which warns the client that results are of lesser fidelity than 
desired, can be sent if the number of pixels had to be restricted to a lesser 
number than max_cells because of a lack of free Colormap cells. The 
AllocRequantize color allocation technique is appropriate only for dynamic 
Colormaps. 


Structures 


XieTecColorAllocRequantize sets the structure field max cells to the value of the 
argument max cells. 


typedef struct { 
unsigned long max _ cells; 
} XieColorAllocRequantizeParam; 


See Also 
XieFloConvertToIndex 


XIElib - Technique Functions XieTecRGBToCIELab 


Name 
XieTecRGBToCIELab - allocate and fill an XieRGBToCIELabParam structure 


Syntax 


XieRGBToCIELabParam *XieTecRGBToCIELab (matrix, white adjust tech, 
white adjust param) 
XieMatrix matrix; 
XieWhiteAdjustTechnique white _adjust_tech; 
XiePointer white adjust param; 


Arguments 
matrix Specifies the conversion matrix. 
white adjust tech Specifies the WhiteAdjust technique to be used. 
white adjust param Specifies the list of parameters required by 
white_adjust_tech. 
Returns 


The XieRGBToCIELabParam structure. 
Description 


XieTecRGBToCIELab allocates and returns a pointer to an 
XieRGBToCIELabParam structure. The returned structure represents the list of 
parameters required by the RGBToCIELab color conversion technique and may 
be used as the color param argument of XieFloConvertFromRGB (when the 
color space argument is xieValRGBToCIELab). 


If insufficient memory is available, XieTecRGBToCIELab returns NULL. To free 
the memory allocated to this structure, use XFree. 


XieTecRGBToCIELab converts RGB data to the CIELab colorspace, an 
international standard designed for perceptual uniformity. The colorspace 
coordinates are denoted by L, a, and b and are defined in CIE, Recommendations 
on Uniform Color Spaces, Color-Difference Equations, Psychometric Color Terms 
(Bureau Central de la CIE [Supplement 2 of CIE Publication 15 (E-1.3.1) 1971], 
1978). 


matrix is a 3x3 RGB-to-CIEXYZ conversion matrix (the source white point is also 
encoded in matrix). white adjust tech is the WhiteAdjust technique that can be 
used to shift the white point of the output data. white adjust param is the list of 
parameters required by white adjust tech. 


The input data type can be constrained or unconstrained; the output data type is 
always unconstrained. When the input is constrained, the data are normalized to 
the range [0, 1] (that is, scaled by 1/(levels - 1) prior to the conversion). 


WhiteAdjust techniques define the white point adjustment techniques that can 
be used when converting to or from the RGB colorspace. One of the following 
standard WhiteAdjust technique values can be assigned to white adjust tech: 


xieValWhiteAdjustDefault 


xieValWhiteAdjustNone 
xieValWhiteAdjustCIELabShift 


If a vendor defined additional private WhiteAdjust techniques, the private 
technique values given to these techniques can be assigned to 
white_adjust_tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Structures 


XieTecRGBToCIELab sets the structure field matrix to the values of the 
argument matrix; the structure field white adjust tech to the value of the 
argument white adjust tech; and the structure field white adjust param to the 
value of the argument white adjust param. 


typedef float XieMatrix[9]; 
typedef unsigned XieWhiteAdjustTechnique; 
typedef struct { 
XieMatrix matrix; 
XieWhiteAdjustTechnique white adjust tech; 
XiePointer white adjust param; 
} XieRGBToCIELabParam; 


/* Definitions for WhiteAdjust Techniques */ 


#define xieValWhiteAdjustDefault 0 

#define xieValWhiteAdjustNone 1 

#define xieValWhiteAdjustCIELabShift 2 
See Also 


XieFloConvertFromRGB, XieTecWhiteAdjustCIELabShift 


XIElib - Technique Functions XieTecRGBToCIEXYZ 


Name 
XieTecRGBToCIEXYZ - allocate and fill an XieRGBToCIEXYZParam structure 


Syntax 


XieRGBToCIEXYZParam *XieTecRGBToCIEXYZ (matrix, white _adjust_tech, 
white adjust param) 
XieMatrix matrix; 
XieWhiteAdjustTechnique white _adjust_tech; 
XiePointer white adjust param; 


Arguments 
matrix Specifies the conversion matrix. 
white adjust tech Specifies the WhiteAdjust technique to be used. 
white adjust param Specifies the list of parameters required by 
white_adjust_tech. 
Returns 


The XieRGBToCIEXYZParam structure. 


Description 


XieTecRGBToCIEXYZ allocates and returns a pointer to an 
XieRGBToCIEXYZParam structure. The returned structure represents the list of 
parameters required by the RGBToCIEXYZ color conversion technique and may 
be used as the color param argument of XieFloConvertFromRGB (when the 
color space argument is xieValRGBToCIEXYZ). 


If insufficient memory is available, XieTecRGBToCIEXYZ returns NULL. To free 
the memory allocated to this structure, use XFree. 


XieTecRGBToCIEXYZ converts RGB data to the CIEXYZ colorspace, an 
international standard device-independent colorspace. 


matrix is a 3x3 RGB-to-CIEXYZ conversion matrix (the source white point is also 
encoded in matrix). white _adjust_tech is the WhiteAdjust technique that can be 
used to shift the white point of the output data. white adjust param is the list of 
parameters required by white adjust tech. 


The input data type can be constrained or unconstrained; the output data type is 
always unconstrained. When the input is constrained, the data are normalized to 
the range [0, 1] (that is, scaled by 1/(levels - 1) prior to the conversion). 


WhiteAdjust techniques define the white point adjustment techniques that can 
be used when converting to or from the RGB colorspace. One of the following 
standard WhiteAdjust technique values can be assigned to white adjust tech: 


xieValWhiteAdjustDefault 
xieValWhiteAdjustNone 
xieValWhiteAdjustCIELabShift 


If a vendor defined additional private WhiteAdjust techniques, the private 
technique values given to these techniques can be assigned to 
white_adjust_tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Structures 


XieTecRGBToCIEXYZ sets the structure field matrix to the values of the 
argument matrix; the structure field white adjust tech to the value of the 
argument white adjust tech; and the structure field white adjust param to the 
value of the argument white adjust param. 


typedef float XieMatrix[9]; 
typedef unsigned XieWhiteAdjustTechnique; 
typedef struct { 
XieMatrix matrix; 
XieWhiteAdjustTechnique white adjust tech; 
XiePointer white adjust param; 
} XieRGBToCIEXYZParam; 


/* Definitions for WhiteAdjust Techniques */ 
#define xieValWhiteAdjustDefault 


#define xieValWhiteAdjustNone 1 
#define xieValWhiteAdjustCIELabShift 2 
See Also 


XieFloConvertFromRGB, XieTecWhiteAdjustCIELabShift 


XIElib - Technique Functions XieTecRGBToYCbCr 


Name 
XieTecRGBToYCbCr - allocate and fill an XieRGBToYCbCrParam structure 


Syntax 


XieRGBToYCbCrParam *XieTecRGBToYCbCr (levels, luma_red, luma_green, 
luma_blue, bias) 
XieLevels levels; 
double luma_red; 
double luma_green; 
double luma_blue; 
XieConstant bias; 


Arguments 
levels Specifies the output levels. 
luma_red Specifies the proportion of red in the luminance band. 
luma_green Specifies the proportion of green in the luminance band. 
luma_blue Specifies the proportion of blue in the luminance band. 
bias Specifies an offset to add to the output pixels values. 
Returns 


The XieRGBToYCbCrParam structure. 


Description 


XieTecRGBToYCbCr allocates and returns a pointer to an XieRGBToYCbCrParam 
structure. The returned structure represents the list of parameters required by 
the RGBToYCbCr color conversion technique and may be used as the 

color param argument of XieFloConvertFromRGB (when the color_space 
argument is xieValRGBToYCbCr). 


If insufficient memory is available, XieTecRGBToYCbCr returns NULL. To free 
the memory allocated to this structure, use XFree. 


XieTecRGBToYCbCr converts RGB data to the YCbCr colorspace. Source data 
may be constrained or unconstrained; the output type will match. If the source 
data is constrained, levels determines the output levels; otherwise levels is 
ignored. 


Structures 


XieTecRGBToYCbCr sets the structure field levels to the values of the argument 
levels; the structure fields luma_ red, luma green, luma_ blue to the values of the 
arguments luma_red, luma_ green, luma_blue; and the structure field bias to the 
values of the argument bias. 


typedef float XieConstant[3]; 
typedef unsigned long XieLevels[3]; 
typedef struct { 

XieLevels levels; 

float luma_red; 

float luma_green; 

float luma_ blue; 


XieConstant bias; 
} XieRGBToYCbCrParam; 


See Also 
XieFloConvertFromRGB 


XIElib - Technique Functions XieTecRGBToYCC 


Name 
XieTecRGBToYCC - allocate and fill an XieRGBToYCCParam structure 
Syntax 


XieRGBToYCCParam *XieTecRGBToYCC (levels, luma_red, luma_green, 
luma_blue, scale) 
XieLevels levels; 
double luma_red; 
double luma_green; 
double luma_blue; 
double scale; 


Arguments 
levels Specifies the output levels. 
luma_red Specifies the proportion of red in the luminance band. 
luma_green Specifies the proportion of green in the luminance band. 
luma_blue Specifies the proportion of blue in the luminance band. 
scale Specifies a compression factor to apply to the output 

pixels values. 
Returns 


The XieRGBToYCCParam structure. 
Description 


XieTecRGBToYCC allocates and returns a pointer to an XieRGBToYCCParam 
structure. The returned structure represents the list of parameters required by 
the RGBToYCC color conversion technique and may be used as the color param 
argument of XieFloConvertFromRGB (when the color space argument is 
xieValRGBToYCC). 


If insufficient memory is available, XieTecRGBToYCC returns NULL. To free the 
memory allocated to this structure, use XFree. 


XieTecRGBToYCC converts RGB data to the YCC colorspace. The PhotoYCC 
color-encoding scheme is defined in: KODAK PhotoCD System - A Planning Guide 
for Developers (Eastman Kodak Co., Part no. DCI2Z00R, 1991). 


Source data may be constrained or unconstrained; the output type will match. If 
the source data is constrained, levels determines the output levels; otherwise 
levels is ignored. Typical values cited in the literature for scale are in the range 
of about 1.35 to 1.4. 


Structures 


XieTecRGBToYCC sets the structure field levels to the values of the argument 
levels; the structure fields luma_ red, luma green, luma_ blue are set to the values 
of the arguments luma_red, luma_green, luma_blue; and the structure field scale 
to the value of the argument scale. 


typedef unsigned long XieLevels[3]; 
typedef struct { 


XieLevels levels; 
float luma_red; 
float luma_green; 
float luma_ blue; 
float scale; 

} XieRGBToYCCParam; 


See Also 
XieFloConvertFromRGB 


XIElib - Technique Functions XieTecCIELabToRGB 


Name 
XieTecCIELabToRGB - allocate and fill an XieCIELabToRGBParam structure 
Syntax 


XieCIELabToRGBParam *XieTecCIELabToRGB (matrix, white adjust tech, 
white adjust param, gamut tech, gamut_param) 
XieMatrix matrix; 
XieWhiteAdjustTechnique white _adjust_tech; 
XiePointer white adjust param; 
XieGamutTechnique gamut tech; 
XiePointer gamut_param; 


Arguments 

matrix Specifies the conversion matrix. 

white adjust tech Specifies the WhiteAdjust technique to be used. 

white adjust param Specifies the list of parameters required by 

white_adjust_tech. 

gamut _tech Specifies the Gamut technique to be used. 

gamut _ param Specifies the list of parameters required by gamut_tech. 
Returns 


The XieCIELabToRGBParam structure. 
Description 


XieTecCIELabToRGB allocates and returns a pointer to an 
XieCIELabToRGBParam structure. The returned structure represents the list of 
parameters required by the CIELabToRGB color conversion technique and may 
be used as the color param argument of XieFloConvertToRGB (when the 

color space argument is xieValCIELabToRGB). 


If insufficient memory is available, XieTecCIELabToRGB returns NULL. To free 
the memory allocated to this structure, use XFree. 


XieTecCIELabToRGB converts CIELab data to the RGB colorspace. The CIELab 
colorspace is an international standard designed for perceptual uniformity. The 
colorspace coordinates are denoted by L, a, and b and are defined in CIE, 
Recommendations on Uniform Color Spaces, Color-Difference Equations, 
Psychometric Color Terms (Bureau Central de la CIE [Supplement 2 of CIE 
Publication 15 (E-1.3.1) 1971], 1978). 


matrix is a 3x3 CIEXYZ-to-RGB conversion matrix (the target white point is also 
encoded in matrix). white _adjust_ tech is the WhiteAdjust technique that can be 
used to shift the white point of the source data prior to conversion. 

white adjust param is the list of parameters required by white adjust tech. 
gamut _tech is the Gamut technique that can be used to keep the output pixels 
within the bounds of the RGB colorspace. gamut_param is the list of parameters 
required by gamut tech. 


The input data type must be unconstrained; the output data type is also 
unconstrained. 


WhiteAdjust techniques define the white point adjustment techniques that can 
be used when converting to or from the RGB colorspace. One of the following 
standard WhiteAdjust technique values can be assigned to white adjust tech: 


xieValWhiteAdjustDefault 
xieValWhiteAdjustNone 
xieValWhiteAdjustCIELabShift 


If a vendor defined additional private WhiteAdjust techniques, the private 
technique values given to these techniques can be assigned to 
white_adjust_tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Gamut techniques define the gamut compression techniques used to deal with 
converted colors that lie outside the gamut of the RGB space. One of the 
following standard gamut technique values can be assigned to gamut_tech: 


xieValGamutDefault 
xieValGamutNone 
xieValGamutClipRGB 


If a vendor defined additional private gamut techniques, the private technique 
values given to these techniques can be assigned to gamut tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Structures 


XieTecCIELabToRGB sets the structure field matrix to the values of the 
argument matrix; the structure field white adjust tech to the value of the 
argument white adjust tech; the structure field white adjust param to the value 
of the argument white adjust param; the structure field gamut_tech to the value 
of the argument gamut tech; and the structure field gamut param to the value 
of the argument gamut _ param. 


typedef float XieMatrix[9]; 
typedef unsigned XieGamutTechnique; 
typedef unsigned XieWhiteAdjustTechnique; 
typedef struct { 
XieMatrix matrix; 
XieWhiteAdjustTechnique white adjust tech; 
XiePointer white adjust param; 
XieGamutTechnique gamut tech; 
XiePointer gamut param; 
} XieCIELabToRGBParam; 


/* Definitions for WhiteAdjust Techniques */ 


#define xieValWhiteAdjustDefault 0 
#define xieValWhiteAdjustNone 1 
#define xieValWhiteAdjustCIELabShift 2 


/* Definitions for Gamut Techniques */ 


#define xieValGamutDefault 0 


#define xieValGamutNone 1 
#define xieValGamutClipRGB 2 
See Also 


XieFloConvertToRGB, XieTecWhiteAdjustCIELabShift 


XIElib - Technique Functions XieTecCIEXYZToRGB 


Name 
XieTecCIEXYZToRGB - allocate and fill an XieCIEXYZToRGBParam structure 


Syntax 


XieCIEXYZToRGBParam *XieTecCIEXYZToRGB (matrix, white_adjust_tech, 
white adjust param, gamut tech, gamut_param) 
XieMatrix matrix; 
XieWhiteAdjustTechnique white _adjust_tech; 
XiePointer white adjust param; 
XieGamutTechnique gamut tech; 
XiePointer gamut_param; 


Arguments 

matrix Specifies the conversion matrix. 

white adjust tech Specifies the WhiteAdjust technique to be used. 

white adjust param Specifies the list of parameters required by 

white_adjust_tech. 

gamut _tech Specifies the Gamut technique to be used. 

gamut _ param Specifies the list of parameters required by gamut _tech. 
Returns 


The XieCIEXYZToRGBParam structure. 


Description 


XieTecCIEXYZToRGB allocates and returns a pointer to an 
XieCIEXYZToRGBParam structure. The returned structure represents the list of 
parameters required by the CIEXYZToRGB color conversion technique and may 
be used as the color param argument of XieFloConvertToRGB (when the 

color space argument is xieValCIEXYZToRGB). 


If insufficient memory is available, XieTecCIEXYZToRGB returns NULL. To free 
the memory allocated to this structure, use XFree. 


XieTecCIEXYZToRGB converts CIEXYZ data to the RGB colorspace. The CIEXYZ 
colorspace is an international standard device-independent colorspace. 


matrix is a 3x3 CIEXYZ-to-RGB conversion matrix (the target white point is also 
encoded in matrix). white _adjust_tech is the WhiteAdjust technique that can be 
used to shift the white point of the source data prior to conversion. 

white adjust param is the list of parameters required by white adjust tech. 
gamut _ tech is the Gamut technique that can be used to keep the output pixels 
within the bounds of the RGB colorspace. gamut_param is the list of parameters 
required by gamut tech. 


The input data type must be unconstrained; the output data type is also 
unconstrained. 


WhiteAdjust techniques define the white point adjustment techniques that can 
be used when converting to or from the RGB colorspace. One of the following 
standard WhiteAdjust technique values can be assigned to white adjust tech: 


xieValWhiteAdjustDefault 
xieValWhiteAdjustNone 
xieValWhiteAdjustCIELabShift 


If a vendor defined additional private WhiteAdjust techniques, the private 
technique values given to these techniques can be assigned to 
white_adjust_tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Gamut techniques define the gamut compression techniques used to deal with 
converted colors that lie outside the gamut of the RGB space. One of the 
following standard gamut technique values can be assigned to gamut _tech: 


xieValGamutDefault 
xieValGamutNone 
xieValGamutClipRGB 


If a vendor defined additional private gamut techniques, the private technique 
values given to these techniques can be assigned to gamut tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Structures 


XieTecCIEXYZToORGB sets the structure field matrix to the values of the 
argument matrix; the structure field white adjust tech to the value of the 


argument white adjust tech; the structure field white adjust param to the value 
of the argument white adjust param; the structure field gamut_tech to the value 


of the argument gamut tech; and the structure field gamut param to the value 
of the argument gamut param. 


typedef float XieMatrix[9]; 
typedef unsigned XieGamutTechnique; 
typedef unsigned XieWhiteAdjustTechnique; 
typedef struct { 
XieMatrix matrix; 
XieWhiteAdjustTechnique white adjust tech; 
XiePointer white adjust param; 
XieGamutTechnique gamut tech; 
XiePointer gamut param; 
} XieCIEXYZToRGBParam; 


/* Definitions for WhiteAdjust Techniques */ 


#define xieValWhiteAdjustDefault 0 
#define xieValWhiteAdjustNone 1 
#define xieValWhiteAdjustCIELabShift 2 
/* Definitions for Gamut Techniques */ 

#define xieValGamutDefault 0 
#define xieValGamutNone 1 


#define xieValGamutClipRGB 2 


See Also 
XieFloConvertToRGB, XieTecWhiteAdjustCIELabShift 


XIElib - Technique Functions XieTecYCbCrTIoRGB 


Name 
XieTecYCbCrToRGB - allocate and fill an XieYCbCrToRGBParam structure 


Syntax 


XieYCbCrToRGBParam *XieTecYCbCrToRGB (levels, luma_red, luma_green, 
luma_blue, bias, gamut_tech, gamut_param) 
XieLevels levels; 
double luma_red; 
double luma_green; 
double Juma_blue; 
XieConstant bias; 
XieGamutTechnique gamut tech; 
XiePointer gamut_param; 


Arguments 
levels Specifies the output levels. 
luma_red Specifies the proportion of red in the luminance band 
(Y). 
luma_green Specifies the proportion of green in the luminance band 
(Y). 
luma_blue Specifies the proportion of blue in the luminance band 
(Y). 
bias Specifies an offset to remove from the source pixels 
values. 
gamut _tech Specifies the Gamut technique to be used. 
gamut _param Specifies the list of parameters required by gamut_tech. 
Returns 


The XieYCbCrToRGBParam structure. 


Description 


XieTecYCbCrToRGB allocates and returns a pointer to an XieYCbCrToRGBParam 
structure. The returned structure represents the list of parameters required by 
the YCbCrToRGB color conversion technique and may be used as the 
color _ param argument of XieFloConvertToRGB (when the color space argument 
is xieValYCbCrToRGB). 


If insufficient memory is available, XieTecYCbCrToRGB returns NULL. To free 
the memory allocated to this structure, use XFree. 


XieTecYCbCrToRGB converts YCbCr data to the RGB colorspace. Source data 
may be constrained or unconstrained; the output type will match. If the source 
data is constrained, levels determines the output levels; otherwise levels is 
ignored. 


Gamut techniques define the gamut compression techniques used to deal with 
converted colors that lie outside the gamut of the RGB space. One of the 
following standard gamut technique values can be assigned to gamut_tech: 


xieValGamutDefault 


xieValGamutNone 
xieValGamutClipRGB 


If a vendor defined additional private gamut techniques, the private technique 
values given to these techniques can be assigned to gamut _tech. 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Structures 


XieTecYCbCrToRGB sets the structure field levels to the values of the argument 
levels; the structure fields luma_ red, luma green, luma_ blue to the values of the 
arguments luma_red, luma_ green, luma_blue; the structure field bias to the 
values of the argument bias; the structure field gamut _tech to the value of the 
argument gamut tech; and the structure field gamut param to the value of the 
argument gamut_param. 


typedef float XieConstant[3]; 
typedef unsigned long XieLevels[3]; 
typedef unsigned XieGamutTechnique; 
typedef struct { 

XieLevels levels; 

float luma_red; 

float luma_green; 

float luma_ blue; 

XieConstant bias; 

XieGamutTechnique gamut tech; 

XiePointer gamut _ param; 
} XieYCbCrToRGBParam; 


/* Definitions for Gamut Techniques */ 


#define xieValGamutDefault 0 

#define xieValGamutNone 1 

#define xieValGamutClipRGB 2 
See Also 


XieFloConvertToRGB 


XIElib - Technique Functions XieTecYCCToRGB 


Name 
XieTecYCCToORGB - allocate and fill an XieYCCToRGBParam structure 


Syntax 


XieYCCToRGBParam *XieTecYCCToRGB (levels, luma_red, luma_green, 
luma_blue, scale, gamut_tech, gamut_param) 
XieLevels levels; 
double luma_red; 
double luma_green; 
double luma_blue; 
double scale; 
XieGamutTechnique gamut tech; 
XiePointer gamut_param; 


Arguments 
levels Specifies the output levels. 
luma_red Specifies the proportion of red in the luminance band 
(Y). 
luma_green Specifies the proportion of green in the luminance band 
(Y). 
luma_blue Specifies the proportion of blue in the luminance band 
(Y). 
scale Specifies an expansion factor to apply to the output 
pixels values. 
gamut tech Specifies the Gamut technique to be used. 
gamut _param Specifies the list of parameters required by gamut_tech. 
Returns 


The XieYCCToRGBParam structure. 


Description 


XieTecYCCToRGB allocates and returns a pointer to an XieYCCToRGBParam 
structure. The returned structure represents the list of parameters required by 
the YCCToRGB color conversion technique and may be used as the color param 
argument of XieFloConvertToRGB (when the color space argument is 
xieValYCCToRGB). 


If insufficient memory is available, XieTecYCCToRGB returns NULL. To free the 
memory allocated to this structure, use XFree. 


XieTecYCCToRGB converts YCC data to the RGB colorspace. The PhotoYCC 
color-encoding scheme is defined in KODAK PhotoCD System - A Planning Guide 
for Developers (Eastman Kodak Co., Part no. DCI200R, 1991). 


Source data may be constrained or unconstrained; the output type will match. If 
the source data is constrained, levels determines the output levels; otherwise 
levels is ignored. Typical values cited in the literature for scale are in the range 
of about 1.35 to 1.4. 


Gamut techniques define the gamut compression techniques used to deal with 
converted colors that lie outside the gamut of the RGB space. One of the 
following standard gamut technique values can be assigned to gamut_tech: 


xieValGamutDefault 
xieValGamutNone 
xieValGamutClipRGB 


If a vendor defined additional private gamut techniques, the private technique 
values given to these techniques can be assigned to gamut tech . 


The server is required to support the default technique that is bound to one of 
the standard techniques defined or a private technique. 


Structures 


XieTecYCCToRGB sets the structure field levels to the values of the argument 
levels; the structure fields luma_ red, luma green, luma_ blue to the values of the 
arguments luma_red, luma_ green, luma_blue; the structure field scale to the 
values of the argument scale; the structure field gamut tech to the value of the 
argument gamut tech; and the structure field gamut param to the value of the 
argument gamut_param. 


typedef unsigned long XieLevels[3]; 
typedef unsigned XieGamutTechnique; 
typedef struct { 

XieLevels levels; 

float luma_red; 

float luma_green; 

float luma_blue; 

float scale; 

XieGamutTechnique gamut tech; 

XiePointer gamut param; 
} XieYCCToRGBParam; 


/* Definitions for Gamut Techniques */ 


#define xieValGamutDefault 0 

#define xieValGamutNone 1 

#define xieValGamutClipRGB 2 
See Also 


XieFloConvertToRGB 


XIElib - Technique Functions XieTecClipScale 


Name 


XieTecClipScale - allocate and fill an XieClipScaleParam structure 
Syntax 


XieClipScaleParam *XieTecClipScale (in_low, in_high, out_low, out_high) 
XieConstant in low; 
XieConstant in_high; 
XieLTriplet out_low; 
XieLTriplet out_high; 


Arguments 
in low Specifies an input pixel limit. 
in_high Specifies an input pixel limit. 
out low Specifies an output pixel limit. 
out high Specifies an output pixel limit. 
Returns 


The XieClipScaleParam structure. 
Description 


XieTecClipScale allocates and returns a pointer to an XieClipScaleParam 
structure. The returned structure represents the list of parameters required by 
the constrain technique and may be used as the constrain_param argument of 
XieFloConstrain (when the constrain tech argument is xieValClipScale). 


If insufficient memory is available, XieTecClipScale returns NULL. To free the 
memory allocated to this structure, use XFree. 


For each band, output pixels will be clipped to the range [out low, out_high]. If 
in_low is less than in_high, then all pixels less than or equal to in_low will map to 
out low, and all pixels that are greater than or equal to in_high will map to 

out high. All intermediate pixel values are scaled proportionately to the output 
range. Nonintegral output values are rounded to the nearest integer. 


Ifin_low is greater than in_ high, then all pixels that are greater than or equal to 
in low will map to out low, and all pixels that are less than or equal to in_high 
will map to out high. All intermediate pixel values will be linearly mapped to the 
output range, such that in low maps to out low, and in_high maps to out_high. 
Nonintegral output values are rounded to the nearest integer. 


in low should not equal in_ high, out low should be less than out_high, and 
out high should not exceed levels - 1. 


Structures 


XieTecClipScale sets the structure fields input low, input high to the values of 
the arguments in low, in_high; and the structure fields output low, output high 
to the values of the arguments out low, out high. 


typedef float XieConstant[3]; 
typedef unsigned long XieLTriplet[3]; 
typedef struct { 
XieConstant input _low,input_high; 
XieLTriplet output _low,output_high; 
} XieClipScaleParam; 


See Also 


XieFloConstrain 


XIElib - Technique Functions XieTecConvolveConstant 


Name 


XieTecConvolveConstant - allocate and fill an XieConvolveConstantParam 
structure 


Syntax 


XieConvolveConstantParam *XieTecConvolveConstant (constant) 
XieConstant constant; 


Arguments 
constant Specifies the value to use if pixels are required from 
beyond the edge of the image. 
Returns 


The XieConvolveConstantParam structure. 
Description 


XieTecConvolveConstant allocates and returns a pointer to an 
XieConvolveConstantParam structure. The returned structure represents the list 
of parameters required by the convolve technique and may be used as the 
convolve_param argument of XieFloConvolve (when the convolve_ tech argument 
is xieValConvolveConstant). 


If insufficient memory is available, XieTecConvolveConstant returns NULL. To 
free the memory allocated to this structure, use XFree. 


Various methods of handling edge conditions are provided for convolve 
techniques. These techniques determine what pixel values are used when the 
convolve technique requires data beyond the image bounds. Convolve 
techniques come into play only when the kernel is positioned partially off the 
edge of the image. Data around the edges of a process domain are convolved 
with adjacent image pixels wherever possible. A process domain is inserted in 
many element definitions and is used to restrict the element's processing to a 
subset of the source data pixels; it can be either a list-of-rectangles or a control- 
plane. 


The Constant Convolve technique uses the value specified by constant if pixels 
are required from beyond the edge of the image. 


Structures 


XieTecConvolveConstant sets the structure field constant to the value of the 
argument constant. 


typedef float XieConstant[3]; 
typedef struct { 

XieConstant constant; 
} XieConvolveConstantParam; 


See Also 


XieFloConvolve 


XIElib - Technique 
Functions XieTecDecodeUncompressedSingle 


Name 


XieTecDecodeUncompressedSingle - allocate and fill an 
XieDecodeUncompressedSingleParam structure 


Syntax 


XieDecodeUncompressedSingleParam *XieTecDecodeUncompressedSingle 
(fill order, pixel_order, pixel stride, left pad, scanline_pad) 
XieOrientation fill_ order; 
XieOrientation pixel order; 
unsigned int pixel stride; 
unsigned int left pad; 
unsigned int scanline_pad; 


Arguments 
fill order Specifies the method of pixel packing. 
pixel order Specifies pixel ordering within the data stream. 
pixel stride Specifies the number of bits between consecutive pixels 
within a scanline. 
left_pad Specifies the number of pad bits in each scanline. 
scanline_pad Specifies a multiple of bytes to which each scanline is 
padded. 
Returns 


The XieDecodeUncompressedSingleParam structure. 
Description 


XieTecDecodeUncompressedSingle allocates and returns a pointer to an 
XieDecodeUncompressedSingleParam structure. The returned structure 
represents the list of parameters required by the decode technique and may be 
used as the decode_param argument of XieFloImportClientPhoto (when the 
decode _tech argument is xieValDecodeUncompressedSingle). 


If insufficient memory is available, XieTecDecodeUncompressedSingle returns 
NULL. To free the memory allocated to this structure, use XFree. 


The decode uncompressed single technique is used when no compression 
scheme has been applied to single band image data. The parameters define the 
format of the data stream of uncompressed data (the server may reformat the 
data as it chooses prior to processing or storage). When multiple pixels are put 
in the same byte, or a pixel spans multiple bytes, fill order specifies whether the 
pixels (or parts of pixels) are packed into the most or least significant bits of a 
byte first. For pixels that span a byte boundary, pixel order defines whether the 
most or least significant bits of the pixel are transported first within the data 
stream. One of the following standard orientation values can be assigned to 

fill order and pixel order: 


xieValLS First 
xieValMS First 


The following table shows the relationship between fill order and pixel order, 
using two 10-bit pixels, each with two bits of pad (within each pixel the LS-bits 
are “O” and “a”, the MS-bits are “9” and “j”, the pad bits are “p”). 


LSFirst (pixel order) MSFirst (pixel order) 


LSFirst 76543210 dcbapp98 98765432 jihgpp10 
ppjihgfe ppfedcba 


MSFirst 76543210 98ppdcba 98765432 10ppjihg 
jihgfepp fedcbapp 


pixel stride is the number of bits between the start of consecutive pixels within 
a scanline; it must be at least enough bits to contain the number of input levels. 
left_pad is the number of pad bits preceding the first image pixel in each 
scanline; if the server's Alignment attribute is Alignable, or pixel stride fits the 
definition of Alignable, the value of left pad must be a multiple of pixel stride or 
a multiple of 8; otherwise, left pad may be any arbitrary value. scanline_pad 
defines a multiple of bytes to which each scanline is padded; valid values are: 0 
(not aligned), 1, 2, 4, 8, and 16. The total number of bits-per-scanline in the data 
stream includes: left pad, the image data (width x pixel stride), and sufficient 
additional bits to satisfy scanline_pad. 


Structures 


XieTecDecodeUncompressedSingle sets the structure field fill order to the value 
of the argument fill order; the structure field pixel order to the value of the 
argument pixel order; the structure field pixel stride to the value of the 
argument pixel stride; the structure field left pad to the value of the argument 
left_pad; and the structure field scanline pad to the value of the argument 
scanline_pad. 


typedef unsigned XieOrientation; 
typedef struct { 
XieOrientation fill order; 
XieOrientation pixel order; 
unsigned int pixel stride; 
unsigned int left_pad; 
unsigned int scanline pad; 
} XieDecodeUncompressedSingleParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 2 


pany 


See Also 
XieFloImportClientPhoto, XiePutClientData 


XIElib - Technique 
Functions XieTecDecodeUncompressedtTriple 


Name 


XieTecDecodeUncompressedTriple - allocate and fill an 
XieDecodeUncompressedTripleParam structure 


Syntax 


XieDecodeUncompressedTripleParam *XieTecDecodeUncompressedTriple 
(fill order, pixel_order, band order, interleave, pixel stride, 
left_pad, scanline_pad) 

XieOrientation fill_order; 
XieOrientation pixel order; 
XieOrientation band _ order; 
XieInterleave interleave; 
unsigned char pixel stride[3]; 
unsigned char left pad[3]; 
unsigned char scanline_pad[3]; 


Arguments 
fill order Specifies the method of pixel packing. 
pixel order Specifies pixel ordering within the data stream. 
band_order Specifies the order of the image data sent through the 
protocol stream. 
interleave Specifies how the image bands are interleaved. 
pixel stride Specifies the number of bits between consecutive pixels 
within a scanline. 
left_pad Specifies the number of pad bits in each scanline. 
scanline_pad Specifies a multiple of bytes to which each scanline is 
padded. 
Returns 


The XieDecodeUncompressedTripleParam structure. 
Description 


XieTecDecodeUncompressedTriple allocates and returns a pointer to an 
XieDecodeUncompressedTripleParam structure. The returned structure 
represents the list of parameters required by the decode technique and may be 
used as the decode_param argument of XieFloImportClientPhoto (when the 
decode_tech argument is xieValDecodeUncompressedTriple). 


If insufficient memory is available, XieTecDecodeUncompressedTriple returns 
NULL. To free the memory allocated to this structure, use XFree. 


The decode uncompressed triple technique is used when no compression scheme 
has been applied to triple band image data. The parameters define the format of 
the data stream of uncompressed data (the server may reformat the data as it 
chooses prior to processing or storage). When multiple pixels are put in the 
same byte, or a pixel spans multiple bytes, fill order specifies whether the pixels 
(or parts of pixels) are packed into the most or least significant bits of a byte 
first. For pixels that span a byte boundary, pixel order defines whether the most 
or least significant bits of the pixel are transported first within the data stream. 


One of the following standard orientation values can be assigned to fill order 
and pixel_order: 


xieValLS First 
xieValMS First 


The following table shows the relationship between fill order and pixel order, 
using two 10-bit pixels, each with two bits of pad (within each pixel the LS-bits 
are “O” and “a”, the MS-bits are “9” and “j”, the pad bits are “p”) 


LSFirst (pixel order) MSFirst (pixel order) 


LSFirst 76543210 dcbapp98 98765432 jihgpp10 
ppjihgfe ppfedcba 


MSFirst 76543210 98ppdcba 98765432 10ppjihg 
jihgfepp fedcbapp 


pixel stride is the number of bits between the start of consecutive pixels within 
a scanline; It must be at least enough bits to contain the number of input levels. 
left_pad is the number of pad bits preceding the first image pixel in each 
scanline; if the server's Alignment attribute is Alignable, or pixel stride fits the 
definition of Alignable, the value of left pad must be a multiple of pixel stride or 
a multiple of 8; otherwise, left pad may be any arbitrary value. scanline_pad 
defines a multiple of bytes to which each scanline is padded; valid values are: 0 
(not aligned), 1, 2, 4, 8, and 16. The total number of bits-per-scanline in the data 
stream includes: left pad, the image data (width x pixel stride), and sufficient 
additional bits to satisfy scanline_pad. 


interleave describes how the image bands are interleaved (per pixel within a 
single plane, or sent as three separate planes); if interleave is 
xieValBandByPixel, inter-band dimensions must match: the widths and the 
heights of all bands must match. One of the following standard interleave values 
can be assigned to interleave: 


xieValBandByPixel 
xieValBandByPlane 


band _ order is the order of the image bands or image planes as they are 
transmitted through the protocol stream. band _ order can be set to one of the 
standard orientation values. The least significant band of trichromatic data is the 
first band mentioned in the common name of the colorspace : red is the least 
significant band of RGB data. For band-by-pixel data, band_order specifies 
whether this band is put in the least or most significant bits of a pixel: 


LSFirst MSFirst 
BiBo G2G1GoR2 RiRo R2RiRoG2Gi GoBiBo 


For band-by-plane data, band_order specifies whether this band corresponds 
with the least significant or most significant image plane. Each plane is 
transported as a separate data stream: 


| band | __—«iLSFirst MSFirst 
| Od R7Re RsR4 R3R2R1Ro B7BeB 5B4B3B 2B1Bo 


G7 G6G5G4G 3G2 GiGo G7 GeG5G4G 3G2 GiGo 
B7BeB 5B4B3B 2B1Bo R7Re R5Ra R3R2R1Ro 


Structures 


XieTecDecodeUncompressed Triple sets the structure field fill order to the value 
of the argument fill order; the structure field pixel order to the value of the 
argument pixel order; the structure field band_ order to the value of the 
argument band order; the structure field interleave to the value of the argument 
interleave; the structure field pixel stride to the value of the argument 

pixel stride; the structure field left pad to the value of the argument left pad; 
and the structure field scanline pad to the value of the argument scanline_pad. 


typedef unsigned XieOrientation; 

typedef unsigned XieInterleave; 

typedef struct { 
unsigned char left pad[3]; 
XieOrientation fill order; 
unsigned char pixel stride[3]; 
XieOrientation pixel order; 
unsigned char scanline pad[3]; 
XieOrientation band_order; 
XieInterleave interleave; 

} XieDecodeUncompressedTripleParam; 


/* Definitions of Orientation Types */ 


#define xieValLSFirst 1 
#define xieValMSFirst 2 
/* Definitions for Interleave */ 

#define xieValBandByPixel 1 
#define xieValBandByPlane 2 


See Also 
XieFloImportClientPhoto, XiePutClientData 


XIElib - Technique Functions XieTecDecodeG31D 


Name 
XieTecDecodeG31D - allocate and fill an XieDecodeG31DParam structure 
Syntax 


XieDecodeG31DParam *XieTecDecodeG31D (encoded _order, normal, 
radiometric) 
XieOrientation encoded _ order; 
Bool normal; 
Bool radiometric; 


Arguments 
encoded_order Specifies the bit order of the encoded data. 
normal Specifies how the data was processed when it was 
originally encoded. 
radiometric Specifies how “white runs” are decoded. 
Returns 


The XieDecodeG31DParam structure. 
Description 


XieTecDecodeG31D allocates and returns a pointer to an XieDecodeG31DParam 
structure. The returned structure represents the list of parameters required by 
the decode technique and may be used as the decode_param argument of 
XieFloImportClientPhoto (when the decode_tech argument is 
xieValDecodeG31D). 


If insufficient memory is available, XieTecDecodeG31D returns NULL. To free 
the memory allocated to this structure, use XFree. 


CCITT-G31D is the CCITT group 3 one-dimensional encoding technique as 
defined by CCITT T.4, "Standardization of Group 3 Facsimile Apparatus for 
Document Transmission". 


encoded order specifies the bit order of the encoded data. One of the following 
standard orientation values can be assigned to encoded_order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “O”, and the last is bit “7”): 


LSFirst MSFirst 


76543210 76543210 01234567 01234567 


radiometric specifies that “white runs” in the encoded data should be 
represented as image ones upon decode (maximum intensity), or conversely, 
they will be decoded as image zeros if radiometric is False. normal specifies that 


the data was processed according to its normal fill-order when it was originally 
encoded. 


Structures 


XieTecDecodeG31D sets the structure field encoded _ order to the value of the 
argument encoded order; the structure field normal to the value of the argument 
normal; and the structure field radiometric to the value of the argument 
radiometric. 


typedef unsigned XieOrientation; 
typedef struct { 
XieOrientation encoded_ order; 
Bool normal; 
Bool radiometric; 
} XieDecodeG31DParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 


Nr 


See Also 
XieFloImportClientPhoto, XiePutClientData 


XIElib - Technique Functions XieTecDecodeG32D 


Name 
XieTecDecodeG32D - allocate and fill an XieDecodeG32DParam structure 


Syntax 


XieDecodeG32DParam *XieTecDecodeG32D (encoded _order, normal, 
radiometric) 
XieOrientation encoded order; 
Bool normal; 
Bool radiometric; 


Arguments 
encoded_order Specifies the bit order of the encoded data. 
normal Specifies how the data was processed when it was 
originally encoded. 
radiometric Specifies how “white runs” are decoded. 
Returns 


The XieDecodeG32DParam structure. 
Description 


XieTecDecodeG32D allocates and returns a pointer to an XieDecodeG32DParam 
structure. The returned structure represents the list of parameters required by 
the decode technique and may be used as the decode_param argument of 
XieFloImportClientPhoto (when the decode_tech argument is 
xieValDecodeG32D). 


If insufficient memory is available, XieTecDecodeG32D returns NULL. To free 
the memory allocated to this structure, use XFree. 


CCITT-G32D is the CCITT group 3 two-dimensional encoding technique as 
defined by CCITT T.4, "Standardization of Group 3 Facsimile Apparatus for 
Document Transmission". 


encoded order specifies the bit order of the encoded data. One of the following 
standard orientation values can be assigned to encoded_order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “O”, and the last is bit “7”): 


LSFirst MSFirst 


76543210 76543210 01234567 01234567 


radiometric specifies that “white runs” in the encoded data should be 
represented as image ones upon decode (maximum intensity), or conversely, 
they will be decoded as image zeros if radiometric is False. normal specifies that 


the data was processed according to its normal fill-order when it was originally 
encoded. 


Structures 


XieTecDecodeG32D sets the structure field encoded _ order to the value of the 
argument encoded order; the structure field normal to the value of the argument 
normal; and the structure field radiometric to the value of the argument 
radiometric. 


typedef unsigned XieOrientation; 
typedef struct { 
XieOrientation encoded_ order; 
Bool normal; 
Bool radiometric; 
} XieDecodeG32DParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 


Nr 


See Also 
XieFloImportClientPhoto, XiePutClientData 


XIElib - Technique Functions XieTecDecodeG42D 


Name 
XieTecDecodeG42D - allocate and fill an XieDecodeG42DParam structure 


Syntax 


XieDecodeG42DParam *XieTecDecodeG42D (encoded _order, normal, 
radiometric)) 
XieOrientation encoded order; 
Bool normal; 
Bool radiometric; 


Arguments 
encoded_order Specifies the bit order of the encoded data. 
normal Specifies how the data was processed when it was 
originally encoded. 
radiometric Specifies how “white runs” are decoded. 
Returns 


The XieDecodeG42DParam structure. 
Description 


XieTecDecodeG42D allocates and returns a pointer to an XieDecodeG42DParam 
structure. The returned structure represents the list of parameters required by 
the decode technique and may be used as the decode_param argument of 
XieFloImportClientPhoto (when the decode_tech argument is 
xieValDecodeG42D). 


If insufficient memory is available, XieTecDecodeG42D returns NULL. To free 
the memory allocated to this structure, use XFree. 


CCITT-G42D is the CCITT group 4 two-dimensional encoding technique as 
defined by CCITT T.6, "Facsimile Coding Schemes and Coding Control Functions 
for Group 4 Facsimile Apparatus". 


encoded order specifies the bit order of the encoded data. One of the following 
standard orientation values can be assigned to encoded_order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “O”, and the last is bit “7”): 


LSFirst MSFirst 


76543210 76543210 01234567 01234567 


radiometric specifies that “white runs” in the encoded data should be 
represented as image ones upon decode (maximum intensity), or conversely, 
they will be decoded as image zeros if radiometric is False. normal specifies that 


the data was processed according to its normal fill-order when it was originally 
encoded. 


Structures 


XieTecDecodeG42D sets the structure field encoded _ order to the value of the 
argument encoded order; the structure field normal to the value of the argument 
normal; and the structure field radiometric to the value of the argument 
radiometric. 


typedef unsigned XieOrientation; 
typedef struct { 
XieOrientation encoded_ order; 
Bool normal; 
Bool radiometric; 
} XieDecodeG42DParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 


Nr 


See Also 
XieFloImportClientPhoto, XiePutClientData 


XIElib - Technique Functions XieTecDecodeTIFF2 


Name 
XieTecDecodeTIFF2 - allocate and fill an XieDecodeTIFF2Param structure 


Syntax 


XieDecodeTIFF2Param *XieTecDecodeTIFF2 (encoded order, normal, 
radiometric) 
XieOrientation encoded order; 
Bool normal; 
Bool radiometric; 


Arguments 
encoded_order Specifies the bit order of the encoded data. 
normal Specifies how the data was processed when it was 
originally encoded. 
radiometric Specifies how “white runs” are decoded. 
Returns 


The XieDecodeTIFF2Param structure. 
Description 


XieTecDecodeTIFF2 allocates and returns a pointer to an XieDecodeTIFF2Param 
structure. The returned structure represents the list of parameters required by 
the decode technique and may be used as the decode_param argument of 
XieFloImportClientPhoto (when the decode_tech argument is 
xieValDecodeTIFF2). 


If insufficient memory is available, XieTecDecodeTIFF2 returns NULL. To free 
the memory allocated to this structure, use XFree. 


TIFF-2 is modified Huffman encoding as described in "TIFF Tag Image File 
Format", revision 6.0, draft 2, by Aldus Corporation (TIFF compression scheme 
2). 


encoded order specifies the bit order of the encoded data. One of the following 
standard orientation values can be assigned to encoded_order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “O”, and the last is bit “7”): 


LSFirst MSFirst 


76543210 76543210 01234567 01234567 


radiometric specifies that “white runs” in the encoded data should be 
represented as image ones upon decode (maximum intensity), or conversely, 
they will be decoded as image zeros if radiometric is False. normal specifies that 


the data was processed according to its normal fill-order when it was originally 
encoded. 


Structures 


XieTecDecodeTIFF2 sets the structure field encoded order to the value of the 
argument encoded order; the structure field normal to the value of the argument 
normal; and the structure field radiometric to the value of the argument 
radiometric. 


typedef unsigned XieOrientation; 
typedef struct { 
XieOrientation encoded_ order; 
Bool normal; 
Bool radiometric; 
} XieDecodeTIFF2Param; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 


Nr 


See Also 
XieFloImportClientPhoto, XiePutClientData 


XIElib - Technique Functions XieTecDecodeTIFFPackBits 


Name 


XieTecDecodeTIFFPackBits - allocate and fill an XieDecodeTIFFPackBitsParam 
structure 


Syntax 


XieDecodeTIFFPackBitsParam *XieTecDecodeTIFFPackBits (encoded_order, 
normal) 
XieOrientation encoded order; 
Bool normal; 


Arguments 
encoded_order Specifies the bit order of the encoded data. 
normal Specifies how the data was processed when it was 
originally encoded. 
Returns 


The XieDecodeTIFFPackBitsParam structure. 
Description 


XieTecDecodeTIFFPackBits allocates and returns a pointer to an 
XieDecodeTIFFPackBitsParam structure. The returned structure represents the 
list of parameters required by the decode technique and may be used as the 
decode_param argument of XieFloImportClientPhoto (when the decode_tech 
argument is xieValDecodeTIFFPackBits). 


If insufficient memory is available, XieTecDecodeTIFFPackBits returns NULL. To 
free the memory allocated to this structure, use XFree. 


TIFF-PackBits is byte-oriented run-length encoding as described in "TIFF Tag 
Image File Format", revision 6.0, draft 2, by Aldus Corporation (TIFF 
compression scheme 32773). 


encoded order specifies the bit order of the encoded data. One of the following 
standard orientation values can be assigned to encoded_order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “O”, and the last is bit “7”): 


76543210 76543210 01234567 01234567 


normal specifies that the data was processed according to its normal fill-order 
when it was originally encoded. 


Structures 


XieTecDecodeTIFFPackBits sets the structure field encoded order to the value of 


the argument encoded_order and the structure field normal to the value of the 
argument normal. 


typedef unsigned XieOrientation; 
typedef struct { 
XieOrientation encoded_order; 
Bool normal; 
} XieDecodeTIFFPackBitsParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 


Nr 


See Also 
XieFloImportClientPhoto, XiePutClientData 


XIElib - Technique Functions XieTecDecodeJPEGBaseline 


Name 
XieTecDecodeJPEGBaseline - allocate and fill an XieDecodeJPEGBaselineParam 
structure 
Syntax 


XieDecodeJPEGBaselineParam *XieTecDecodeJPEGBaseline (interleave, 
band_order, up sample) 
XieInterleave interleave; 
XieOrientation band _ order; 
Bool up_sample; 


Arguments 
interleave Specifies how the image bands will be interleaved. 
band_order Specifies the order in which the image bands were 
originally encoded. 
up_sample Specifies how interleaved encoded data are up-sampled. 
Returns 


The XieTecDecodeJPEGBaselineParam structure. 
Description 


XieDecodeJPEGBaseline allocates and returns a pointer to an 
XieDecodeJPEGBaselineParam structure. The returned structure represents the 
list of parameters required by the decode technique and may be used as the 
decode_param argument of XieFloImportClientPhoto (when the decode_tech 
argument is xieValDecodeJPEGBaseline). 


If insufficient memory is available, XieTecDecodeJPEGBaseline returns NULL. To 
free the memory allocated to this structure, use XFree. 


The JPEG baseline technique is the baseline Huffman DCT encoding technique 
that is defined in ISO DIS 10918-1 "Digital Compression and Coding of 
Continuous-tone Still Images". Only JPEG Interchange Format (JIF) is supported: 
all tables, compressed data, and so on are embedded in the data stream, all 
delineated by markers. 


interleave determines whether all bands of a triple band image will be 
interleaved within a single encoded stream or whether three separate encoded 
streams will be supplied. One of the following standard interleave values can be 
assigned to interleave: 


xieValBandByPixel 
xieValBandByPlane 


For triple band data, band_ order specifies the order in which the image bands 
were originally encoded. One of the following standard orientation values can 
be assigned to band _ order: 


xieValLS First 
xieValMS First 


The least significant band of trichromatic data is the first band mentioned in the 
common name of the colorspace: red is the least significant band of RGB data. 

band_order specifies whether this band corresponds with the least significant or 
most significant image plane. Each plane is decoded into a separate data stream: 


| band [_ LSFirst | MSFirst 
| 0 ‘| ‘Red band Blue band 


up_sample specifies that if any bands in an interleaved encoded data stream are 
down-sampled, they should be up-sampled by the JPEG decoder. 


The arguments interleave, band order, and up sample are ignored for single 
band images, and up sample is always ignored if interleave is band-by-plane. If 
up_sample is False and some of the encoded bands of an interleaved image were 
down-sampled, an alternative method for up-sampling the image would be to use 
a geometry element with appropriate band_mask and sample technique 
parameters. 


Structures 


XieTecDecodeJPEGBaseline sets the structure field interleave to the value of the 
argument interleave; the structure field band_ order to the value of the argument 
band _order; and the structure field up sample to the value of the argument 
up_sample. 


typedef unsigned XieOrientation; 
typedef struct { 
XieInterleave interleave; 
XieOrientation band_order; 
Bool up sample; 
} XieDecodeJPEGBaselineParam; 
/* Definitions for Interleave */ 


#define xieValBandByPixel 1 
#define xieValBandByPlane 2 
/* Definitions of Orientation Types */ 

#define xieValLSFirst 1 
#define xieValMSFirst 2 


See Also 


XieFloImportClientPhoto, XieFloConvertToRGB, XieTecYCbCrToRGB, 
XiePutClientData 


XIElib - Technique Functions XieTecDecodeJPEGLossless 


Name 
XieTecDecodeJPEGLossless - allocate and fill an XieDecodeJPEGLosslessParam 
structure 
Syntax 


XieDecodeJPEGLosslessParam *XieTecDecodeJPEGLossless (interleave, 
band_order) 
XieInterleave interleave; 
XieOrientation band _ order; 


Arguments 
interleave Specifies how the image bands will be interleaved. 
band_order Specifies the order in which the image bands were 
originally encoded. 
Returns 


The XieDecodeJPEGLosslessParam structure. 
Description 


XieTecDecodeJPEGLossless allocates and returns a pointer to an 
XieDecodeJPEGLosslessParam structure. The returned structure represents the 
list of parameters required by the decode technique and may be used as the 
decode_param argument of XieFloImportClientPhoto (when the decode_tech 
argument is xieValDecodeJPEGLossless). 


If insufficient memory is available, XieTecDecodeJPEGLossless returns NULL. To 
free the memory allocated to this structure, use XFree. 


The JPEG lossless technique is the Huffman predictive sequential lossless 
encoding technique that is defined in ISO DIS 10918-1 "Digital Compression and 
Coding of Continuous-tone Still Images". 

This technique is not available in the R6 sample implementation of XIE. 


interleave describes how the bands of triple band data are interleaved; either all 
bands are interleaved within a single encoded stream, or three separate encoded 
streams are expected. One of the following standard interleave values can be 
assigned to interleave: 


xieValBandByPixel 
xieValBandByPlane 


For triple band data, band_order specifies the order in which the image bands 
were originally encoded. One of the following standard orientation values can be 
assigned to band order: 


xieValLS First 
xieValMS First 


The least significant band of trichromatic data is the first band mentioned in the 
common name of the colorspace: red is the least significant band of RGB data. 


band_order specifies whether this band corresponds with the least significant or 
most significant image plane. Each plane is decoded into a separate data stream: 


| band | LSFirst | MSFirst 
| 0 | Red band Blue band 


The arguments interleave and band order are ignored for single band images. 


Structures 


XieTecDecodeJPEGLossless sets the structure field interleave to the value of the 
argument interleave; and the structure field band _ order to the value of the 
argument band _ order. 


typedef unsigned XieOrientation; 
typedef struct { 
XieInterleave interleave; 
XieOrientation band_order; 
} XieDecodeJPEGLosslessParam; 
/* Definitions for Interleave */ 


#define xieValBandByPixel 1 

#define xieValBandByPlane 2 

/* Definitions of Orientation Types */ 

#define xieValLSFirst 1 

#define xieValMSFirst 2 
See Also 


XieFloImportClientPhoto, XiePutClientData 


XIElib - Technique Functions XieTecDitherOrdered 


Name 
XieTecDitherOrdered - allocate and fill an XieDitherOrderedParam structure 
Syntax 


XieDitherOrderedParam *XieTecDitherOrdered (threshold _ order) 
unsigned int threshold_order; 


Arguments 
threshold_order Specifies a value to determine the size of the dither 
matrix. 
Returns 


The XieDitherOrderedParam structure. 
Description 


XieTecDitherOrdered allocates and returns a pointer to an 
XieDitherOrderedParam structure. The returned structure represents the list of 
parameters required by the decode technique and may be used as the 
decode_param argument of XieFloImportClientPhoto (when the decode_tech 
argument is xieValDitherOrdered). 


If insufficient memory is available, XieTecDitherOrdered returns NULL. To free 
the memory allocated to this structure, use XFree. 


The dispersed-dot ordered dither technique replaces a matrix, or block, of pixels 
with a patterned matrix of pixels. This patterned matrix of pixels is applied 
across the entire image. Because these patterns may introduce artifacts that are 
distracting to the eye, the threshold _ order parameter is available to determine 
the size of the dither matrix, and therefore, the number of levels that can be 
simulated. If the value of threshold _order is m, the threshold matrix can 
simulate 2m + 1 levels. 


Structures 


XieTecDitherOrdered sets the structure field threshold_order to the value of the 
argument threshold _ order. 


typedef struct { 
unsigned int threshold_order; 
} XieDitherOrderedParam; 


See Also 
XieFloDither 


XIElib - Technique 
Functions XieTecEncodeUncompressedSingle 


Name 


XieTecEncodeUncompressedSingle - allocate and fill an 
XieEncodeUncompressedSingleParam structure 


Syntax 


XieEncodeUncompressedSingleParam *XieTecEncodeUncompressedSingle 
(fill order, pixel _order, pixel stride, scanline_pad) 
XieOrientation fill_ order; 
XieOrientation pixel order; 
unsigned int pixel stride; 
unsigned int scanline_pad; 


Arguments 
fill order Specifies the method of pixel packing. 
pixel order Specifies pixel ordering within the data stream. 
pixel stride Specifies the number of bits between consecutive pixels 
within a scanline. 
scanline_pad Specifies a multiple of bytes to which each scanline is 
padded. 
Returns 


The XieEncodeUncompressedSingleParam structure. 
Description 


XieTecEncodeUncompressedSingle allocates and returns a pointer to an 
XieEncodeUncompressedSingleParam structure. The returned structure 
represents the list of parameters required by the encode technique and may be 
used as the encode_param argument of XieFloExportClientPhoto and 
XieFloExportPhotomap (when the encode tech argument is 
xieValEncodeUncompressedSingle). 


If insufficient memory is available, XieTecEncodeUncompressedSingle returns 
NULL. To free the memory allocated to this structure, use XFree. 


The encode uncompressed single technique is used when no compression 
scheme is to be applied to single band image data. The parameters define the 
format of the data stream of uncompressed data that is made available for client 
retrieval via XieGetClientData. When multiple pixels are put in the same byte or 
a pixel spans multiple bytes, fill order specifies whether the pixels (or parts of 
pixels) are packed into the most or least significant bits of a byte first. For pixels 
that span a byte boundary, pixel order defines whether the most or least 
significant bits of the pixel are put first within the data stream. 


One of the following standard orientation values can be assigned to fill order 
and pixel_order: 


xieValLS First 
xieValMS First 


The following table shows the relationship between fill order and pixel order, 
using two 10-bit pixels, each with two bits of pad (within each pixel the LS-bits 
are “O” and “a”, the MS-bits are “9” and “j”, and the pad bits are “p”). 


LSFirst (pixel order) MSFirst (pixel order) 


LSFirst 76543210 dcbapp98 98765432 jihgpp10 
ppjihgfe ppfedcba 


MSFirst 76543210 98ppdcba 98765432 10ppjihg 
jihgfepp fedcbapp 


pixel stride is the number of bits between the start of consecutive pixels within 

a scanline. It must be at least enough bits to contain the number of source levels. 
scanline_pad defines a multiple of bytes to which each scanline is padded; valid 
values are: O (not aligned), 1, 2, 4, 8, and 16. 


Structures 


XieTecEncodeUncompressedSingle sets the structure field fill order to the value 
of the argument fill order; the structure field pixel order to the value of the 
argument pixel order; the structure field pixel stride to the value of the 
argument pixel stride; and the structure field scanline pad to the value of the 
argument scanline_ pad. 


typedef unsigned XieOrientation; 
typedef struct { 
XieOrientation fill order; 
XieOrientation pixel order; 
unsigned int pixel stride; 
unsigned int scanline pad; 
} XieEncodeUncompressedSingleParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 2 


pany 


See Also 
XieFloExportClientPhoto, XieFloExportPhotomap, XieGetClientData 


XIElib - Technique 
Functions XieTecEncodeUncompressedtTriple 


Name 


XieTecEncodeUncompressedTriple - allocate and fill an 
XieEncodeUncompressedTripleParam structure 


Syntax 


XieEncodeUncompressedTripleParam *XieTecEncodeUncompressedTriple 
(fill order, pixel_order, band order, interleave, pixel stride, 
scanline_pad) 

XieOrientation fill_ order; 
XieOrientation pixel order; 
XieOrientation band _ order; 
XieInterleave interleave; 
unsigned char pixel _stride[3]; 
unsigned char scanline_pad[3]; 


Arguments 
fill order Specifies the method of pixel packing. 
pixel order Specifies pixel ordering within the data stream. 
band _ order Specifies the order of the image data sent through the 
protocol stream. 
interleave Specifies how the image bands are interleaved. 
pixel stride Specifies the number of bits between consecutive pixels 
within a scanline. 
scanline_pad Specifies a multiple of bytes to which each scanline is 
padded. 
Returns 


The XieEncodeUncompressedTripleParam structure. 
Description 


XieTecEncodeUncompressedTriple allocates and returns a pointer to an 
XieEncodeUncompressedTripleParam structure. The returned structure 
represents the list of parameters required by the encode technique and may be 
used as the encode_param argument of XieFloExportClientPhoto and 
XieFloExportPhotomap (when the encode tech argument is 
xieValEncodeUncompressedTriple). 


If insufficient memory is available, XieTecEncodeUncompressedTriple returns 
NULL. To free the memory allocated to this structure, use XFree. 


The encode uncompressed triple technique is used when no compression scheme 
is to be applied to triple band image data. The parameters define the format of 
the data stream of uncompressed data that is made available for client retrieval 
via XieGetClientData. When multiple pixels are put in the same byte or a pixel 
spans multiple bytes, fill order specifies whether the pixels (or parts of pixels) 
are packed into the most or least significant bits of a byte first. For pixels that 
span a byte boundary, pixel order defines whether the most or least significant 
bits of the pixel are put first within the data stream. 


One of the following standard orientation values can be assigned to fill order 
and pixel_order: 


xieValLS First 
xieValMS First 


The following table shows the relationship between fill order and pixel order, 
using two 10-bit pixels, each with two bits of pad (within each pixel the LS-bits 
are “O” and “a”, the MS-bits are “9” and “j”, and the pad bits are “p”) 


LSFirst (pixel order) MSFirst (pixel order) 


LSFirst 76543210 dcbapp98 98765432 jihgpp10 
ppjihgfe ppfedcba 


MSFirst 76543210 98ppdcba 98765432 10ppjihg 
jihgfepp fedcbapp 


pixel stride is the number of bits between the start of consecutive pixels within 

a scanline. It must be at least enough bits to contain the number of source levels. 
scanline_pad defines a multiple of bytes to which each scanline is padded; valid 
values are: 0 (not aligned), 1, 2, 4, 8, and 16. band _ order is the order of the 
image bands or image planes as they are transmitted through the protocol 
stream. One of the following standard orientation values can be assigned to 

band _order: 


xieValLS First 
xieValMS First 


The least significant band of trichromatic data is the first band mentioned in the 
common name of the colorspace: red is the least significant band of RGB data. 
For band-by-pixel data, band_order specifies whether this band is put in the least 
or most significant bits of a pixel: 


LSFirst MSFirst 
BiBo G2G1GoR2 RiRo R2RiRoG2Gi GoBiBo 


For band-by-plane data, band_order specifies whether this band corresponds 
with the least significant or most significant image plane. Each plane is 
transported as a separate data stream: 


LSFirst MSFirst 
R7Re R5R4 R3R2R1Ro B7B6B 5B4B3B 2B1Bo 


G7 GeGsG4G3G2 GiGo G7 GeGsG4G3G2GiGo 
B7BeB 5B4B3B 2B1Bo R7Re RsR4 R3R2R1Ro 


interleave describes how the bands are interleaved (per pixel within a single 
plane, or sent as three separate planes). One of the following standard interleave 
values can be assigned to interleave: 


xieValBandByPixel 
xieValBandByPlane 


Export of down-sampled band-by-pixel data is not supported: all bands must 
have equal widths and equal heights. 


Structures 


XieTecEncodeUncompressedtTriple sets the structure field fill order to the value 
of the argument fill order; the structure field pixel order to the value of the 
argument pixel order; the structure field band_ order to the value of the 
argument band _ order; the structure field interleave to the value of the argument 
interleave; the structure field pixel stride to the value of the argument 

pixel stride; and the structure field scanline pad to the value of the argument 
scanline_pad. 


typedef unsigned XieOrientation; 

typedef struct { 
unsigned char pixel stride[3]; 
XieOrientation pixel order; 
unsigned char scanline pad[3]; 
XieOrientation fill order; 
XieOrientation band_order; 
XieInterleave interleave; 

} XieEncodeUncompressedTripleParam; 


/* Definitions of Orientation Types */ 


#define xieValLSFirst 1 
#define xieValMSFirst 2 
/* Definitions for Interleave */ 

#define xieValBandByPixel 1 
#define xieValBandByPlane 2 


See Also 
XieFloExportClientPhoto, XieFloExportPhotomap, XieGetClientData 


XIElib - Technique Functions XieTecEncodeG31D 


Name 
XieTecEncodeG31D - allocate and fill an XieEncodeG31DParam structure 


Syntax 


XieEncodeG31DParam *XieTecEncodeG31D (align _eol, radiometric, 
encoded order) 
Bool align_eol; 
Bool radiometric; 
XieOrientation encoded order; 


Arguments 
align eol Specifies the use of fill bits preceding EOL codes. 
radiometric Specifies how “white runs” are encoded. 
encoded_order Specifies the bit order of the encoded data. 
Returns 


The XieEncodeG31DParam structure. 
Description 


XieTecEncodeG31D allocates and returns a pointer to an XieEncodeG31DParam 
structure. The returned structure represents the list of parameters required by 
the encode technique and may be used as the encode_param argument of 
XieFloExportClientPhoto and XieFloExportPhotomap (when the encode_tech 
argument is xieValEncodeG31D). 


If insufficient memory is available, XieTecEncodeG31D returns NULL. To free 
the memory allocated to this structure, use XFree. 


CCITT-G31D is the CCITT group 3 one-dimensional encoding technique as 
defined by CCITT T.4, "Standardization of Group 3 Facsimile Apparatus for 
Document Transmission". 


If True, align _eol, specifies that sufficient fill bits must precede EOL codes to 
guarantee that each EOL will end on a byte boundary (thus EOL will be a nibble 
of zero followed by a byte of one: xxxx,00002 0000,00012). radiometric specifies 
that image ones will be encoded as “white runs”, or conversely, image zeros will 
be encoded as “white runs”, if radiometric is False. encoded_order specifies the 
bit order for the encoded data. One of the following standard orientation values 
can be assigned to encoded _order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “O”, and the last is bit “7”): 


76543210 76543210 01234567 01234567 


Structures 


XieTecEncodeG31D sets the structure field align eol to the value of the 
argument align eol; the structure field radiometric to the value of the argument 
radiometric; and the structure field encoded _order to the value of the argument 
encoded _ order. 


typedef unsigned XieOrientation; 
typedef struct { 

Bool align_eol; 

Bool radiometric; 

XieOrientation encoded _ order; 
} XieEncodeG31DParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 2 


Re 


See Also 
XieFloExportClientPhoto, XieFloExportPhotomap, XieGetClientData 


XIElib - Technique Functions XieTecEncodeG32D 


Name 
XieTecEncodeG32D - allocate and fill an XieEncodeG32DParam structure 


Syntax 


XieEncodeG32DParam *XieTecEncodeG32D (uncompressed, align _eol, 
radiometric, encoded _order, k_factor) 
Bool uncompressed; 
Bool align_eol; 
Bool radiometric; 
XieOrientation encoded order; 
unsigned long k_factor; 


Arguments 
uncompressed Specifies the use of the uncompressed-mode CCITT 
extension. 
align eol Specifies the use of fill bits preceding EOL codes. 
radiometric Specifies how “white runs” are encoded. 
encoded_order Specifies the bit order of the encoded data. 
k_factor Specifies the number of two-dimensional scanlines to 
produce for each one-dimensional scanline. 
Returns 


The XieEncodeG32DParam structure. 


Description 


XieTecEncodeG32D allocates and returns a pointer to an XieEncodeG32DParam 
structure. The returned structure represents the list of parameters required by 
the encode technique and may be used as the encode_param argument of 
XieFloExportClientPhoto and XieFloExportPhotomap (when the encode _tech 
argument is xieValEncodeG32D). 


If insufficient memory is available, XieTecEncodeG32D returns NULL. To free 
the memory allocated to this structure, use XFree. 


CCITT-G32D is the CCITT group 3 two-dimensional encoding technique as 
defined by CCITT T.4, "Standardization of Group 3 Facsimile Apparatus for 
Document Transmission". 


If True, uncompressed, will enable the use of the uncompressed-mode CCITT 
extension. If True, align eol, specifies that sufficient fill bits must precede EOL 
codes to guarantee that each EOL will end on a byte boundary (thus EOL will be 
a nibble of zero followed by a byte of one: xxxx,00002 0000,00012). radiometric 
specifies that image ones will be encoded as “white runs”, or conversely, image 
zeros will be encoded as “white runs”, if radiometric is False. encoded_order 
specifies the bit order for the encoded data. One of the following standard 
orientation values can be assigned to encoded _order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “O”, and the last is bit “7”): 


76543210 76543210 01234567 01234567 


k_factor specifies the number of two-dimensional scanlines to produce for each 
one-dimensional scanline. 


Structures 


XieTecEncodeG32D sets the structure field uncompressed to the value of the 
argument uncompressed; the structure field align eol to the value of the 
argument align eol; the structure field radiometric to the value of the argument 
radiometric; the structure field encoded order to the value of the argument 
encoded order; and the structure field k factor to the value of the argument 
k_factor. 


typedef unsigned XieOrientation; 
typedef struct { 
Bool uncompressed; 
Bool align _eol; 
Bool radiometric; 
XieOrientation encoded _ order; 
unsigned long k factor; 
} XieEncodeG32DParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 2 


pany 


See Also 
XieFloExportClientPhoto, XieFloExportPhotomap, XieGetClientData 


XIElib - Technique Functions XieTecEncodeG42D 


Name 
XieTecEncodeG42D - allocate and fill an XieEncodeG42DParam structure 


Syntax 


XieEncodeG42DParam *XieTecEncodeG42D (uncompressed, radiometric, 
encoded order) 
Bool uncompressed; 
Bool radiometric; 
XieOrientation encoded order; 


Arguments 
uncompressed Specifies the use of the uncompressed-mode CCITT 
extension. 
radiometric Specifies how “white runs” are encoded. 
encoded_order Specifies the bit order of the encoded data. 
Returns 


The XieEncodeG42DParam structure. 
Description 


XieTecEncodeG42D allocates and returns a pointer to an XieEncodeG42DParam 
structure. The returned structure represents the list of parameters required by 
the encode technique and may be used as the encode_param argument of 
XieFloExportClientPhoto and XieFloExportPhotomap (when the encode_tech 
argument is xieValEncodeG42D). 


If insufficient memory is available, XieTecEncodeG42D returns NULL. To free 
the memory allocated to this structure, use XFree. 


CCITT-G42D is the CCITT group 4 two-dimensional encoding technique as 
defined by CCITT T.6, "Facsimile Coding Schemes and Coding Control Functions 
for Group 4 Facsimile Apparatus". 


If True, uncompressed will enable the use of the uncompressed-mode CCITT 
extension. radiometric specifies that image ones will be encoded as “white runs”, 
or conversely, image zeros will be encoded as “white runs”, if radiometric is 
False. encoded order specifies the bit order for the encoded data. One of the 
following standard orientation values can be assigned to encoded order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “O”, and the last is bit “7”): 


76543210 76543210 01234567 01234567 


Structures 


XieTecEncodeG42D sets the structure field uncompressed to the value of the 
argument uncompressed; the structure field radiometric to the value of the 
argument radiometric; and the structure field encoded _ order to the value of the 
argument encoded order. 


typedef unsigned XieOrientation; 
typedef struct { 

Bool uncompressed; 

Bool radiometric; 

XieOrientation encoded _ order; 
} XieEncodeG42DParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 2 


Re 


See Also 
XieFloExportClientPhoto, XieFloExportPhotomap, XieGetClientData 


XIElib - Technique Functions XieTecEncodeServerChoice 


Name 


XieTecEncodeServerChoice - allocate and fill an XieEncodeServerChoiceParam 
structure 


Syntax 


XieEncodeServerChoiceParam *XieTecEncodeServerChoice (preference) 
unsigned int preference; 


Arguments 
preference Specifies a “hint” to help the server make its choice. 
Returns 


The XieEncodeServerChoiceParam structure. 


Description 


XieTecEncodeServerChoice allocates and returns a pointer to an 
XieEncodeServerChoiceParam structure. The returned structure represents the 
list of parameters required by the encode technique and may be used as the 
encode_param argument of XieFloExportPhotomap (when the encode _tech 
argument is xieValEncodeServerChoice). 


If insufficient memory is available, XieTecEncodeServerChoice returns NULL. To 
free the memory allocated to this structure, use XFree. 


The server choice technique allows the server to choose an encode technique 
when exporting to a photomap. A photomap is a server resource that can be 
used to store image data. preference specifies an optional “hint” that can be 
provided to help the server make its choice, but the server is not obligated to 
obey the hint. One of the following standard server choice preference values can 
be assigned to preference: 


xieValPreferDefault 
xieValPreferSpace 
xieValPreferTime 


xieValPreferTime hints that retrieval performance is the desired metric, whereas 
xieValPreferSpace indicates that frugal use of storage space is more important. 
Normally the server choice technique must choose a lossless encode technique, 
but when data is received from an adjacent upstream import element, it may 
choose to pass the import element’s input data directly to the photomap. 


Structures 


XieTecEncodeServerChoice sets the structure field preference to the value of the 
argument preference. 


typedef struct { 
unsigned int preference; 
} XieEncodeServerChoiceParam; 


/* Definitions for ServerChoice Preference Hints */ 


#define xieValPreferDefault 
#define xieValPreferSpace 
#define xieValPreferTime 


See Also 
XieFIloExportPhotomap 


XIElib - Technique Functions XieTecEncodeJPEGBaseline 


Name 


XieTecEncodeJPEGBaseline - allocate and fill an XieEncodeJPEGBaselineParam 
structure 


Syntax 


XieEncodeJPEGBaselineParam *XieTecEncodeJPEGBaseline (interleave, 
band_order, horizontal samples, vertical samples, q table, q_ size, 
ac table, ac_size, dc_table, dc size) 

XieInterleave interleave; 
XieOrientation band _ order; 

unsigned char horizontal samples[3]; 
unsigned char vertical samples[3]; 
char *q_ table; 

unsigned int q size; 

char *ac_table; 

unsigned int ac_ size; 

char *dc_table; 

unsigned int dc _ size; 


Arguments 
interleave Specifies how the image bands will be interleaved. 
band _order Specifies the order in which the image bands were 
originally encoded. 
horizontal _samples Specifies the horizontal sampling factor. 
vertical samples Specifies the vertical sampling factor. 
q_table Specifies the quantization table. 
q_size Specifies the number of elements in q_table. 
ac_table Specifies the AC Huffman table. 
ac_size Specifies the number of elements in ac_table. 
dc_table Specifies the DC Huffman table. 
dc_size Specifies the number of elements in dc_table. 
Returns 


The XieEncodeJPEGBaselineParam structure. 
Description 


XieTecEncodeJPEGBaseline allocates and returns a pointer to an 
XieEncodeJPEGBaselineParam structure. The returned structure represents the 
list of parameters required by the encode technique and may be used as the 
encode_param argument of XieFloExportClientPhoto and XieFloExportPhotomap 
(when the encode _tech argument is xieValEncodeJPEGBaseline). 


If insufficient memory is available, XieTecEncodeJPEGBaseline returns NULL. 
XieTecEncodeJPEGBaseline allocates memory for the structure fields q table, 
ac_table, and dc_table; to free the memory allocated to the structure 
XieEncodeJPEGBaselineParam, use XieFreeEncodeJPEGBaseline. 


JPEG-Baseline is baseline Huffman DCT encoding as defined by ISO DIS 10918-1 
"Digital Compression and Coding of Continuous-tone Still Images". A stream of 


JPEG Interchange Format (JIF) data is produced: all tables, compressed data, 
and so on are embedded in the data stream, all delineated by markers. 


For optimal results, clients should ensure that the colorspace of triple band 
image data flowing into ExportClientPhoto or ExportPhotomap, for encoding by 
the JPEGBaseline encoder, is YCbCr. 


interleave determines whether all bands of a triple band image will be 
interleaved within a single encoded stream or whether three separate encoded 
streams will be produced. One of the following standard interleave values can be 
assigned to interleave: 


xieValBandByPixel 
xieValBandByPlane 


For triple band data, band_order specifies the order in which the image bands 
were originally encoded. One of the following standard orientation values can be 
assigned to band _ order: 


xieValLS First 
xieValMS First 


The least significant band of trichromatic data is the first band mentioned in the 
common name of the colorspace: red is the least significant band of RGB data. 
band_order specifies whether this band corresponds with the least significant or 
most significant image plane. Each plane is encoded from a separate data 
stream: 


[band | 1st] isi J) 
| O | Red band Blue band 


The arguments horizontal samples and vertical samples are the horizontal and 
vertical sampling factors. q table is the quantization table. ac_ table specifies the 
AC Huffman table and dc_table specifies the DC Huffman table. 


There may be one q table per band or a single q table shared between all bands. 
Generally there is a single AC/DC pair of Huffman tables, but for triple band 
band-by-pixel data there may be two pairs of tables (one for the luminance band 
and the other for the chromanance bands). If any table is specified with zero 
length, it indicates that the server implementor is to supply that table (for 
example, the example tables defined in ISO DIS 10918-1 "Digital Compression 
and Coding of Continuous-tone Still Images"). 


The arguments interleave, band _ order, horizontal samples, and vertical samples 
are ignored for single band images, and horizontal samples and vertical_samples 
are always ignored if interleave is band-by-plane. horizontal samples and 
vertical samples share the definitions and restrictions stipulated for parameters 
Hi and Vi, respectively, that are specified in annexes A and B of ISO DIS 10918-1 
"Digital Compression and Coding of Continuous-tone Still Images". 


Structures 


XieTecEncodeJPEGBaseline sets the structure field interleave to the value of the 
argument interleave; the structure field band_order to the value of the argument 
band _order; the structure field horizontal sample to the values of the argument 
horizontal sample; the structure field vertical sample to the values of the 
argument vertical sample; and the structure fields q table, q size, ac table, 

ac size, dc table, dc size to the values of the arguments q table, q size, 
ac_table, ac_size, dc table, dc size. 


typedef unsigned XieOrientation; 
typedef struct { 
XieInterleave interleave; 
XieOrientation band_order; 
unsigned char horizontal samples[3]; 
unsigned char vertical samples[3]; 
char *q_table; 
unsigned int q_size; 
char *ac_table; 
unsigned int ac _size; 
char *dc_table; 
unsigned int dc_ size; 
} XieEncodeJPEGBaselineParam; 


/* Definitions for Interleave */ 


#define xieValBandByPixel 1 
#define xieValBandByPlane 2 
/* Definitions of Orientation Types */ 

#define xieValLSFirst 1 
#define xieValMSFirst 2 


See Also 


XieFloExportClientPhoto, XieFloExportPhotomap, XieFreeEncodeJPEGBaseline, 
XieFloConvertFromRGB, XieTecRGBToYCbCr, XieGetClientData 


XIElib - Technique Functions XieTecEncodeJPEGLossless 


Name 
XieTecEncodeJPEGLossless - allocate and fill an XieEncodeJPEGLosslessParam 
structure 
Syntax 


XieEncodeJPEGLosslessParam *XieTecEncodeJPEGLossless (interleave, 
band_order, predictor, table, table_size) 
XieInterleave interleave; 
XieOrientation band _ order; 
unsigned char predictor[3]; 
char *table; 
unsigned int table size; 


Arguments 
interleave Specifies how the image bands will be interleaved. 
band_order Specifies the order in which the image bands were 
originally encoded. 
predictor Specifies the predictor selection value. 
table Specifies the lossless entropy encoding table. 
table _ size Specifies the number of elements in table. 
Returns 


The XieEncodeJPEGLosslessParam structure. 
Description 


XieTecEncodeJPEGLossless allocates and returns a pointer to an 
XieEncodeJPEGLosslessParam structure. The returned structure represents the 
list of parameters required by the encode technique and may be used as the 
encode_param argument of XieFloExportClientPhoto and XieFloExportPhotomap 
(when the encode tech argument is xieValEncodeJPEGLossless). 


If insufficient memory is available, XieTecEncodeJPEGLossless returns NULL. 
XieTecEncodeJPEGLossless allocates memory for the structure field table; to free 
the memory allocated to the structure XieEncodeJPEGLosslessParam, use 
XieFreeEncodeJPEGLossless. 


JPEG-Lossless, corresponds to frames encoded using Huffman, predictive 
sequential lossless encoding as defined by ISO DIS 10918-1 "Digital 
Compression and Coding of Continuous-tone Still Images". A data stream of 
JPEG Interchange Format (JIF) data is returned: all tables, compressed data, and 
so on are embedded in the data stream, all delineated by markers. 

This technique is not available in the R6 sample implementation of XIE. 


interleave determines whether all bands of a triple band image will be 
interleaved within a single encoded stream or whether three separate encoded 
streams will be produced. One of the following standard interleave values can be 
assigned to interleave: 


xieValBandByPixel 


xieValBandByPlane 


For triple band data, band_ order specifies the order in which the image bands 
were originally encoded. One of the following standard orientation values can 
be assigned to band _ order: 


xieValLS First 
xieValMS First 


The least significant band of trichromatic data is the first band mentioned in the 
common name of the colorspace: red is the least significant band of RGB data. 
band_order specifies whether this band corresponds with the least significant or 
most significant image plane. Each plane is encoded from a separate data 
stream: 


[hand [sist ist 7 
| 0 | Red band Blue band 


The arguments interleave and band order are ignored for single band images. 


predictor is the predictor selection value (one per band). table is the lossless 
entropy encoding table (up to one per band). Specifying a table of length zero 
indicates that the server implementor should supply a table (for example, the 
example tables defined in ISO DIS 10918-1 "Digital Compression and Coding of 
Continuous-Tone Still Images"). 


Structures 


XieTecEncodeJPEGLossless sets the structure field interleave to the value of the 
argument interleave; the structure field band_ order to the value of the argument 
band _order; the structure field predictor to the values of the argument 
predictor; and the structure fields table, table size to the values of the 
arguments table, table size. 


typedef unsigned XieOrientation; 
typedef struct { 
XieInterleave interleave; 
XieOrientation band_order; 
unsigned char predictor[3]; 
char *table; 
unsigned int table size; 
} XieEncodeJPEGLosslessParam; 
/* Definitions for Interleave */ 


#define xieValBandByPixel 1 
#define xieValBandByPlane 2 
/* Definitions of Orientation Types */ 

#define xieValLSFirst 1 


#define xieValMSFirst 2 


See Also 
XieFloExportClientPhoto, XieFloExportPhotomap, XieGetClientData 


XIElib - Technique Functions XieTecEncodeTIFF2 


Name 
XieTecEncodeTIFF2 - allocate and fill an XieEncodeTIFF2Param structure 
Syntax 


XieEncodeTIFF2Param *XieTecEncodeTIFF2 (encoded _ order, radiometric) 
XieOrientation encoded _ order; 
Bool radiometric; 


Arguments 
encoded_order Specifies the bit order of the encoded data. 
radiometric Specifies how “white runs” are decoded. 
Returns 


The XieEncodeTIFF2Param structure. 
Description 


XieTecEncodeTIFF2 allocates and returns a pointer to an XieEncodeTIFF2Param 
structure. The returned structure represents the list of parameters required by 
the encode technique and may be used as the encode_param argument of 
XieFloExportClientPhoto and XieFloExportPhotomap (when the encode _tech 
argument is xieValEncodeTIFF2). 


If insufficient memory is available, XieTecEncodeTIFF2 returns NULL. To free 
the memory allocated to this structure, use XFree. 


TIFF-2 is modified Huffman compression as described in "TIFF Tag Image File 
Format", revision 6.0, draft 2, by Aldus Corporation (TIFF compression scheme 
2). 


radiometric specifies that image ones will be encoded as “white runs”, or 
conversely, image zeros will be encoded as “white runs”, if radiometric is False. 
encoded order specifies the bit order for the encoded data. One of the following 
standard orientation values can be assigned to encoded_order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “0”, and the last is bit “7”): 


76543210 76543210 01234567 01234567 


Structures 


XieTecEncodeTIFF2 sets the structure field encoded order to the value of the 
argument encoded order; and the structure field radiometric to the value of the 
argument radiometric. 


typedef unsigned XieOrientation; 


typedef struct { 
XieOrientation encoded_order; 
Bool radiometric; 

} XieEncodeTIFF2Param; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 2 


pany 


See Also 
XieFloExportClientPhoto, XieFloExportPhotomap, XieGetClientData 


XIElib - Technique Functions XieTecEncodeTIFFPackBits 


Name 
XieTecEncodeTIFFPackBits - allocate and fill an XieEncodeTIFFPackBitsParam 
structure 
Syntax 


XieEncodeTIFFPackBitsParam *XieTecEncodeTIFFPackBits (encoded_order) 
XieOrientation encoded order; 


Arguments 

encoded_order Specifies the bit order of the encoded data. 
Returns 

The XieEncodeTIFFPackBitsParam structure. 


Description 


XieTecEncodeTIFFPackBits allocates and returns a pointer to an 
XieEncodeTIFFPackBitsParam structure. The returned structure represents the 
list of parameters required by the encode technique and may be used as the 
encode_param argument of XieFloExportClientPhoto and XieFloExportPhotomap 
(when the encode_tech argument is xieValEncodeTIFFPackBits). 


If insufficient memory is available, XieTecEncodeTIFFPackBits returns NULL. To 
free the memory allocated to this structure, use XFree. 


TIFF-PackBits is byte-oriented run-length encoding as described in "TIFF Tag 
Image File Format", revision 6.0, draft 2, by Aldus Corporation (TIFF 
compression scheme 32773). 


encoded order specifies the bit order of the encoded data. One of the following 
standard orientation values can be assigned to encoded_order: 


xieValLS First 
xieValMS First 


The following table shows the encoded bit order of two bytes (within each byte 
the first encoded bit is “O”, and the last is bit “7”): 


76543210 76543210 01234567 01234567 


Structures 


XieTecEncodeTIFFPackBits sets the structure field encoded _order to the value of 
the argument encoded order. 


typedef unsigned XieOrientation; 
typedef struct { 

XieOrientation encoded _ order; 
} XieEncodeTIFFPackBitsParam; 


/* Definitions of Orientation Types */ 
#define xieValLSFirst 
#define xieValMSFirst 


Nr 


See Also 
XieFloExportClientPhoto, XieFloExportPhotomap, XieGetClientData 


XIElib - Technique Functions XieTecGeomAntialiasByArea 


Name 

XieTecGeomAntialiasByArea - allocate and fill an XieGeomAntialiasByAreaParam 

structure 

Syntax 

XieGeomAntialiasByAreaParam *XieTecGeomAntialiasByArea (simple) 

int simple; 

Arguments 

simple Specifies the approximation form to use. 
Returns 


The XieGeomAntialiasByAreaParam structure. 
Description 


XieTecGeomAntialiasByArea allocates and returns a pointer to an 
XieGeomAntialiasByAreaParam structure. The returned structure represents the 
list of parameters required by the geometry technique and may be used as the 
sample param argument of XieFloGeometry (when the sample tech argument is 
xieValGeomAntialiasByArea). 


If insufficient memory is available, XieTecGeomAntialiasByArea returns NULL. 
To free the memory allocated to this structure, use XFree. 


Antialiasing techniques incorporate information from an "area" of pixels in the 
input image in order to produce each output pixel. This implies that line 
dropouts and other artifacts will occur less often, and the output image may 
have markedly better resemblance to the input image. The technique 
AntialiasByArea computes the output image by assigning to each output pixel 
the weighted average of the intensity values of input pixels that fall within its 
“area”. That is, the four corners of the output pixel are projected back onto the 
input image. 


If simple is zero (0), the size and shape of the "area" are determined by the 
parameters of the geometric transformation. The boundaries of the "area" may 
not fall on pixel boundaries and, in the case of nonorthogonal rotation of the 
image, "area" may not be rectangular. Partial input pixel values may have to be 
calculated: the antialias-by-area technique preserves shape but can be very slow 
computationally. 


Because of the computational complexity of this method, two approximations are 
supported. If simple is nonzero, the pixels covered by the projected area will be 
averaged without regard to the relative amount of area that they contain: if they 
are touched by the area, they are included in a simple average. If simple is set to 
N, with N odd and greater than one (3,5,7, ...), then only the center point of the 
output pixel is projected, and a simple average is taken of an N by N window 
centered on the projection. For best results, N should correspond roughly to the 
amount of scaling that will be done. 


Structures 


XieTecGeomAntialiasByArea sets the structure field simple to the value of the 
argument simple. 


typedef struct { 


int simple; 
} XieGeomAntialiasByAreaParam; 


See Also 
XieFloGeometry 


XIElib - Technique 


Functions XieTecGeomAntialiasByLowpass 


Name 


XieTecGeomAntialiasByLowpass - allocate and fill an 
XieGeomAntialiasByLowpassParam structure 


Syntax 


XieGeomAntialiasByLowpassParam *XieTecGeomAntialiasByLowpass 
(kernel size) 
int kernel size; 


Arguments 

kernel _size Specifies the size of the image kernel. 
Returns 

The XieGeomAntialiasByLowpassParam structure. 
Description 


XieTecGeomAntialiasByLowpass allocates and returns a pointer to an 
XieGeomAntialiasByLowpassParam structure. The returned structure represents 
the list of parameters required by the geometry technique and may be used as 
the sample_param argument of XieFloGeometry (when the sample_tech 
argument is xieValGeomAntialiasByLowpass). 


If insufficient memory is available, XieTecGeomAntialiasByLowpass returns 
NULL. To free the memory allocated to this structure, use XFree. 


Antialiasing techniques incorporate information from an "area" of pixels in the 
input image in order to produce each output pixel. This implies that line 
dropouts and other artifacts will occur less often, and the output image may 
have markedly better resemblance to the input image. The technique 
AntialiasByLowpass represents an approximation to antialias-by-area that can be 
faster, yet provides similar results. First, a low-pass filter is applied by passing 
an nxn boxcar kernel over the original input image. Output pixel values are then 
derived using a nearest neighbor sampling method that selects the value of the 
input pixel in the upper-left corner of the area mapped back from the output 
pixel. 


The user is allowed to select the size of the image kernel via the kernel size 
parameter. For best results, kernel size should be chosen to correspond roughly 
to the amount of scaling that will be done. Note that the server chooses the best 
kernel for the appropriate size; the values used in the kernel are not alterable by 
the client application. Clients wishing to specify the kernel in more detail should 
use the convolve technique directly. 


Structures 


XieTecGeomAntialiasByLowpass sets the structure field kernel size to the value 
of the argument kernel size. 


typedef struct { 
int kernel size; 


} XieGeomAntialiasByLowpassParam; 


See Also 
XieFloGeometry, XieFloConvolve, XieTecGeomAntialiasByArea 


XIElib - Technique Functions XieTecGeomGaussian 


Name 


XieTecGeomGaussian - allocate and fill an XieGeomGaussianParam structure 
Syntax 


XieGeomGaussianParam *XieTecGeomGaussian (sigma, normalize, radius, 
simple) 
double sigma; 
double normalize; 
unsigned int radius; 
Bool simple; 


Arguments 
sigma Specifies the drop-off rate. 
normalize Specifies a normalization constant. 
radius Specifies the extent of computation. 
simple Specifies the approximation form to use. 
Returns 


The XieGeomGaussianParam structure. 
Description 


XieTecGeomGaussian allocates and returns a pointer to an 
XieGeomGaussianParam structure. The returned structure represents the list of 
parameters required by the geometry technique and may be used as the 
sample_param argument of XieFloGeometry (when the sample tech argument is 
xieValGeomGaussian). 


If insufficient memory is available, XieTecGeomGaussian returns NULL. To free 
the memory allocated to this structure, use XFree. 


A Geometry element can be visualized as stepping through each possible output 
pixel location in turn, and computing the location from which to obtain each 
input pixel value. Each pixel (x',y') in the output image is mapped to the 
coordinate location (x,y) in src by: 


It is not unusual that the input location (x,y) so derived will be nonintegral and 
will not correspond exactly to a single pixel in the input image. 


From sampling theory, a bandwidth limited continuous input image can be 
recovered perfectly (under certain conditions) from its sampled output by 
computing the convolution: 


Here I(x,y) is the continuous image, i(m,n) the discrete sampled image, and 
h(u, v) is the impulse response function for an appropriate low-pass filter. The 
specific form of h(u,v) for a Gaussian impulse response function is given by: 


The term is called the "normalization constant" and may be altered using the 
normalize parameter. The suggested value for (sigma, the drop-off rate) is 1. 
Note that all technique parameters must be chosen in concert 


radius defines the extent of computation. A suggested value for radius is one, 
that is, only pixels within a distance of one in either the x or y direction are 
involved in the calculation. 


For computational convenience, a simplified form of Gaussian interpolation is 
provided. If simple is True, the impulse-response function h(u,v) is: 


The normalization factor N is defined by normalize. As with true Gaussian 
interpolation, the radius parameter is used to determine the number of pixels 
involved in the computation. 


Structures 


XieTecGeomGaussian sets the structure field sigma to the value of the argument 
sigma; the structure field normalize to the value of the argument normalize; the 
structure field radius to the value of the argument radius; and the structure field 
simple to the value of the argument simple. 


typedef struct { 
float sigma; 
float normalize; 
unsigned int radius; 
Bool simple; 

} XieGeomGaussianParam; 


See Also 
XieFloGeometry 


XIElib - Technique FunctionsXie TecGeomNearestNeighbor 


Name 


XieTecGeomNearestNeighbor - allocate and fill an 
XieGeomNearestNeighborParam structure 


Syntax 


XieGeomNearestNeighborParam *XieTecGeomNearestNeighbor (modify) 
unsigned int modify; 


Arguments 


modify Specifies technique behavior on even boundaries. 


Returns 


The XieGeomNearestNeighborParam structure. 


Description 


XieTecGeomNearestNeighbor allocates and returns a pointer to an 
XieGeomNearestNeighborParam structure. The returned structure represents 
the list of parameters required by the geometry technique and may be used as 
the sample_param argument of XieFloGeometry (when the sample_tech 
argument is xieValGeomNearestNeighbor). 


If insufficient memory is available, XieTecGeomNearestNeighbor returns NULL. 
To free the memory allocated to this structure, use XFree. 


A Geometry element can be visualized as stepping through each possible output 
pixel location in turn, and computing the location from which to obtain each 
input pixel value. Each pixel (x',y') in the output image is mapped to the 
coordinate location (x,y) in src by: 


It is not unusual that the input location (x,y) so derived will be nonintegral and 
will not correspond exactly to a single pixel in the input image. 


To illustrate NearestNeighbor technique, assume that the pixel grid locations P, 
Q, R, and S are integral. Pixel location X = (x,y)T, obtained from the mapping 
equation above, differs from P by fractional amounts s in the x direction and t in 
the y direction. 


Let I(P) be the value of the input image at coordinate P, if P is within the image 

extent. Otherwise, let I(P) be constant, where constant is the pixel value passed 
to the Geometry element. A value of [(X) must be estimated from I(P), I(Q), I(R), 
and [(S). In nearest-neighbor sampling, we simply choose the image value from 
the discrete location closest to X. Thus, 


ifs < 1/2, t < 1/2, set I(X) = I(P), 
ifs > 1/2, t < 1/2, set I(X) = I(Q), 
ifs > 1/2, t > 1/2, set I(X) = I(R), 


ifs < 1/2, t > 1/2, set I(X) = I(S). 


The behavior on even boundaries (s = 1/2 or t = 1/2) is determined by the modify 
parameter. One of the standard nearest neighbor modify values can be assigned 
to modify: 


xieValFavorDown 
xieValFavorUp 
xieValRoundNW 
xieValRoundNE 
xieValRoundSE 
xieValRoundSW 


If modify is xieValFavorDown, all “less than” signs in the above are replaced with 
“less than” or “equal “signs. Thus, P would win all ties, S and Q would lose to P 
but win over R, and R would lose all ties. If modify is xieValFavorUp, then all 
greater than signs would be replaced with greater than or equals, and the 
opposite behavior would occur. Four additional options are provided. The 
xieValRoundxx options will always choose a specific integral pixel grid location; 
these are not strictly nearest neighbor algorithms but are available for 
computational/filtering convenience. 


Structures 


XieTecGeomNearestNeighbor sets the structure field modify to the value of the 
argument modify. 


typedef struct { 
unsigned int modify; 
} XieGeomNearestNeighborParam; 
/* Definitions of NearestNeighbor Modify */ 
#define xieValFavorDown 
#define xieValFavorUp 
#define xieValRoundNW 
#define xieValRoundNE 
#define xieValRoundSE 
#define xieValRoundSW 


AN PWNF 


See Also 
XieFloGeometry 


XIElib - Technique Functions XieTecHistogramGaussian 


Name 


XieTecHistogramGaussian - allocate and fill an XieHistogramGaussianParam 
structure 


Syntax 


XieHistogramGaussianParam *XieTecHistogramGaussian (mean, sigma) 
double mean; 
double sigma; 


Arguments 
mean Specifies the center of the Gaussian probability density 
function. 
sigma Specifies the "spread" of the Gaussian probability 
density function. 
Returns 


The XieHistogramGaussianParam structure. 
Description 


XieTecHistogramGaussian allocates and returns a pointer to an 
XieHistogramGaussianParam structure. The returned structure represents the 
list of parameters required by the match-histogram shape technique and may be 
used as the shape param argument of XieFloMatchHistogram (when the shape 
argument is xieValHistogramGaussian). 


If insufficient memory is available, XieTecHistogramGaussian returns NULL. To 
free the memory allocated to this structure, use XFree. 


The Gaussian match-histogram shape technique specifies that the output image 
is to have a histogram that approximates a Gaussian probability density. The 
supplied parameters are used to generate a Gaussian probability density 
function centered around the mean level with a “spread” specified by sigma: 


Structures 


XieTecHistogramGaussian sets the structure field mean to the value of the 
argument mean; and the structure field sigma to the value of the argument 
sigma. 


typedef struct { 
float mean; 
float sigma; 
} XieHistogramGaussianParam; 


See Also 


XieFloMatchHistogram 


XIElib - Technique Functions XieTecHistogramHyperbolic 


Name 
XieTecHistogramHyperbolic - allocate and fill an XieHistogramHyperbolicParam 
structure 
Syntax 
XieHistogramHyperbolicParam *XieTecHistogramHyperbolic (constant, 
shape _factor) 
double constant; 
Bool shape_factor; 
Arguments 
constant Specifies a value used to generate a hyperbolic 
probability density function 
shape _factor Specifies the relationship between the histogram shape 
and image levels. 
Returns 


The XieHistogramHyperbolicParam structure. 
Description 


XieTecHistogramHyperbolic allocates and returns a pointer to an 
XieHistogramHyperbolicParam structure. The returned structure represents the 
list of parameters required by the match-histogram shape technique and may be 
used as the shape _ param argument of XieFloMatchHistogram (when the shape 
argument is xieValHistogramHyperbolic). 


If insufficient memory is available, XieTecHistogramHyperbolic returns NULL. 
To free the memory allocated to this structure, use XFree. 


The hyperbolic match-histogram shape technique specifies that the output image 
is to have a histogram that approximates a hyperbolic probability density. 


constant is used to generate a hyperbolic probability density function: 


shape _ factor should be specified as False if the histogram shape represents 
decreasing values for higher levels or True if the shape represents increasing 
values for higher levels. 


Structures 


XieTecHistogramHyperbolic sets the structure field constant to the value of the 
argument constant; and the structure field shape factor to the value of the 
argument shape factor. 


typedef struct { 
float constant; 
Bool shape factor; 
} XieHistogramHyperbolicParam; 


See Also 
XieFloMatchHistogram 


XIElib - Technique 


Functions XieTe cWhiteAdjustCIE LabShift 


Name 


XieTecWhiteAdjustCIELabShift - allocate and fill an 
XieWhiteAdjustCIELabShiftParam structure 


Syntax 


XieWhiteAdjustCIELabShiftParam *XieTecWhiteAdjustCIELabShift (white_point) 
XieConstant white_point; 


Arguments 

white point Specifies the white point of the (source or output) data. 
Returns 

The XieWhiteAdjustCIELabShiftParam structure. 
Description 


XieTecWhiteAdjustCIELabShift allocates and returns a pointer to an 
XieWhiteAdjustCIELabShiftParam structure. The returned structure represents 
the list of parameters required by the WhiteAdjust technique and may be used as 
the white adjust param argument of XieTecRGBToCIELab, XieTecRGBToCIEXYZ, 
XieTecCIELabToRGB, and XieTecCIEXYZToRGB (when the white adjust_tech 
argument is xieValWhiteAdjustCIELabShift). 


If insufficient memory is available, XieTecWhiteAdjustCIELabShift returns NULL. 
To free the memory allocated to this structure, use XFree. 


White point correction can be used to ensure that white "looks" white, or it can 
be used to change the overall tint of an image. 


The CIELabShift WhiteAdjust technique specifies that white point correction is 
to be accomplished by adding the white point displacement to the ab plane in 
the CIELab colorspace. The white_ point is specified using CIEXYZ encodings. If 
the WhiteAdjust technique is used with a color conversion technique that 
converts from RGB, white point specifies the desired white point of the output 
data; if the conversion is to RGB, white point specifies the white point of the 
source data. 


Structures 


XieTecWhiteAdjustCIELabShift sets the structure field white point to the value 
of the argument white_ point. 


typedef float XieConstant[3]; 
typedef unsigned XieWhiteAdjustTechnique; 
typedef struct { 
XieConstant white point; 
} XieWhiteAdjustCIELabShiftParam; 


See Also 


XieTecRGBToCIELab, XieTecRGBToCIEXYZ, XieTecCIELabToRGB, 
XieTecCIEXYZToRGB 


XIElib - Free Functions XieFreeTechniques 


Name 
XieFreeTechniques - free memory allocated for a list of techniques 
Syntax 


void XieFreeTechniques (techs, count) 
XieTechnique *techs; 
unsigned int count; 


Arguments 
techs Specifies the list of techniques to be freed. 
count Specifies the number of items in the list of techniques to 
be freed. 
Description 


XieFreeTechniques frees the memory previously allocated for techs. Care should 
be taken that the argument pair techs/count match an argument pair 
techniques _ret/ntechniques ret returned from XieQueryTechniques. 


See XieQueryTechniques for a description of the XieTechnique structure. 
Structures 


typedef unsigned XieTechniqueGroup; 
typedef struct { 
Bool needs param; 
XieTechniqueGroup group; 
unsigned int number; 
unsigned int speed; 
char *name; 
} XieTechnique; 


See Also 
XieQueryTechniques 


XIElib - Free Functions XieFreePhotofloGraph 


Name 


XieFreePhotofloGraph - free memory allocated for an array of XiePhotoElement 
structures 


Syntax 


void XieFreePhotofloGraph (elements, count) 
XiePhotoElement *elements; 
unsigned int count; 


Arguments 
elements Specifies the array of XiePhotoElement structures to be 
freed. 
count Specifies the number of XiePhotoElement structures in 
the array. 
Description 


XieFreePhotofloGraph frees the specified array of XiePhotoElement structures. 


Care should be taken that the argument pair elements/count match a returned 
value (an array of XiePhotoElement structures) and argument count from a call 
to XieAllocatePhotofloGraph. 


Technique parameters are not freed by using XieFreePhotofloGraph. Most of the 
technique parameters, with the exception of the JPEG baseline and JPEG lossless 
encode techniques, which are allocated using XIElib convenience functions are 
freed using XFree. This is so the client can reuse technique parameters between 
photoflos. 


Structures 


typedef struct { 
int elemType; 
/* union of ALL element types */ 
union { 


} data; 
} XiePhotoElement; 


See Also 


XieAllocatePhotofloGraph, XieCreatePhotoflo, XieExecutePhotoflo, 
XieExecuteImmediate 


XIElib - Free Functions XieFreeEncodeJPEGBaseline 


Name 


XieFreeEncodeJPEGBaseline - free the memory allocated to the structure 
XieEncodeJPEGBaselineParam 


Syntax 


void XieFreeEncodeJPEGBaseline (param) 
XieEncodeJPEGBaselineParam *param 


Arguments 


param Specifies a pointer to the structure that is to be freed. 


Description 


XieFreeEncodeJPEGBaseline (rather than XFree) should be used to free the 
memory allocated by XieTecEncodeJPEGBaseline. 


Structures 


typedef struct { 
XieInterleave interleave; 
XieOrientation band_ order; 
unsigned char horizontal samples[3]; 
unsigned char vertical samples[3]; 
char *q_table; 
unsigned int q_size; 
char *ac_table; 
unsigned int ac_size; 
char *dc_table; 
unsigned int dc_ size; 

} XieEncodeJPEGBaselineParam; 


See Also 
XieTecEncodeJPEGBaseline 


XIElib - Free Functions XieFreeEncodeJPEGLossless 


Name 


XieFreeEncodeJPEGLossless - free the memory allocated to the structure 
XieEncodeJPEGLosslessParam 


Syntax 


void XieFreeEncodeJPEGLossless (param) 
XieEncodeJPEGLosslessParam *param; 


Arguments 


param Specifies a pointer to the structure that is to be freed. 


Description 


XieFreeEncodeJPEGLossless (rather than XFree) should be used to free the 
memory allocated by XieTecEncodeJPEGLossless. 


Note that the JPEG Lossless technique is not available in the R6 sample 
implementation of XIE. 


Structures 


typedef struct { 
XieInterleave interleave; 
XieOrientation band_order; 
unsigned char predictor[3]; 
char *table; 
unsigned int table size; 

} XieEncodeJPEGLosslessParam; 


See Also 
XieTecEncodeJPEGLossless 


XIElib - Free Functions XieFreePasteUpTiles 


Name 
XieFreePasteUptTiles - free the memory allocated to the tiles field of a PasteUp 
structure 
Syntax 


void XieFreePasteUpTiles (element) 
XiePhotoElement *element; 


Arguments 
element Specifies the XiePhotoElement structure to use. 


Description 


XieFreePasteUpTiles frees the memory allocated to the tiles field in the specified 
PasteUp member structure; after the memory has been freed, the field value is 


set to NULL. 


Structures 


typedef struct { 
int elemType; 
union { 


struct { 
unsigned int width; 
unsigned int height; 
XieConstant constant; 
XieTile *tiles; 
unsigned int tile count; 
} PasteUp; 


} data; 
} XiePhotoElement; 


See Also 
XieFloPasteUp 


XIEFlib Events ColorAlloc 


Description 


The client is notified that a ConvertToIndex element has completed color 
allocation, but has produced a result of lesser fidelity than was requested using 
the technique that was specified for the ConvertToIndex element. 


The structure fields name space, flo id, src, and elem _ type identify the photoflo 
and specific ConvertToIndex element from which the ColorAlloc event 
originated. The structure field time is the server time when the ColorAlloc event 
occurred, in milliseconds. The structure field color list is the color list resource 
that received the allocated colors. The structure field color alloc technique is 
the ColorAlloc technique specified to the ConvertToIndex element. The structure 
field color alloc data can be used for other information that is specific to the 
ColorAlloc technique. 


Structures 


/* ColorAlloc Event Code */ 
#define xieEvnNoColorAlloc 0 


typedef struct { 
int type; 
unsigned long serial; 
Bool send_event; 
Display *display; 
unsigned long name _ space; 
Time time; 
unsigned long flo id; 
XiePhototag src; 
unsigned int elem_type; 
XieColorList color list; 
XieColorAllocTechnique color alloc technique; 
unsigned long color alloc data; 
} XieColorAllocEvent; 


See Also 
XieFloConvertToIndex, XieTecColorAllocAll 


XIElib Events DecodeNotify 


Description 


A DecodeNotify event notifies the client that anomalies were encountered while 
decoding a compressed image (see the notify arguments of 
XieFloImportClientPhoto and XieFloImportPhotomap). Either an error has been 
encountered while decoding an image, or the image data received does not 
satisfy the expected dimensions. 


The structure fields name space, flo id, src, and elem type identify the photoflo 
and element from which the DecodeNotify event originated. The structure field 
time is the server time when the DecodeNotify event occurred, in milliseconds. 
The structure field band number associates the event with a specific band of the 
image. The structure field decode technique is the Decode technique being 
used. The structure fields width and height are the dimensions discovered while 
decoding the data. The structure field aborted is True if decoding was aborted, 
or False if recovery was possible. 


Recovery from a decode error may result in some missing or garbled image data. 
This may also cause the height of the decoded data to be less than was expected. 
If the structure fields width or height do not match the width and height 
specified to XieFloImportClientPhoto, the image data is clipped or padded (with 
zeros), as required, to enforce the XieFloImportClientPhoto specified 
dimensions. 


Structures 


/* DecodeNotify Event Code */ 
#define xieEvnNoDecodeNotify 1 


typedef struct { 
int type; 
unsigned long serial; 
Bool send event; 
Display *display; 
unsigned long name _ space; 
Time time; 
unsigned long flo_ id; 
XiePhototag src; 
unsigned int elem_type; 
XieDecodeTechnique decode _ technique; 
Bool aborted; 
unsigned int band_number; 
unsigned long width; 
unsigned long height; 

} XieDecodeNotifyEvent; 


See Also 
XieFloImportClientPhoto, XieFloImportPhotomap 


XIElib Events ExportAvailable 


Description 


The client is notified that an ExportClient element has data available (see the 
notify argument of the applicable XieFloExportClient... function). If notify was 
specified as xieValFirstData, this event will be sent only the first time data 
become available from the ExportClient element. Otherwise (that is, 
xieValNewData was specified), this event will be generated each time the 
amount of data available changes from zero to nonzero. 


The structure fields name space, flo id, src, and elem _ type identify the photoflo 
and specific ExportClient element from which the ExportAvailable event 
originated. The structure field time is the server time when the ExportAvailable 
event occurred, in milliseconds. The structure field band number associates the 
event with a specific band of the image or LUT. The structure field data is 
information specific to elem_type (for example, the number of LUT entries or 
ROI rectangles available). 


Where there is a single ExportClient element, the client can just read bytes or be 
event-driven. For photoflos containing multiple ExportClient elements, the client 
should be event-driven. 


Structures 


/* ExportAvailable Event Code */ 
#define xieEvnNoExportAvailable 2 


typedef struct { 
int type; 
unsigned long serial; 
Bool send_event; 
Display *display; 
unsigned long name _ space; 
Time time; 
unsigned long flo id; 
XiePhototag src; 
unsigned int elem_type; 
unsigned int band_number; 
unsigned long data[3]; 

} XieExportAvailableEvent; 


See Also 


XieFIoExportClientHistogram, XieFloExportClientLUT, XieFloExportClientPhoto, 
XieFloExportClientROI 


XIElib Events 


Description 


ImportObscured 


The client is notified when an ImportDrawable or ImportDrawablePlane element 
encounters obscured regions in a Window that cannot be retrieved from backing 
store (see the notify argument of the import element routine). A separate 
ImportObscured event is returned for each affected region. 


The structure fields name space, flo id, and src identify the photoflo and the 
specific import element from which the ImportObscured event originated. The 
structure field time is the server time when the ImportObscured event occurred, 
in milliseconds. The structure field window identifies the Window. The obscured 
region of the window is specified by the structure fields x, y, width, and height. 


Note: image data within obscured regions will be populated with the fill 


argument supplied to the import element. 


Structures 


/* ImportObscured Event Code */ 
#define xieEvnNoImportObscured 


typedef struct { 


int type; 


unsigned long serial; 
Bool send event; 
Display *display; 
unsigned long name _ space; 
Time time; 

unsigned long flo_ id; 
XiePhototag src; 
unsigned int elem_type; 
Window window; 

int x; 

int y; 

unsigned int width; 
unsigned int height; 


} XieImportObscuredEvent; 
See Also 
XieFloImportDrawable, XieFloImportDrawablePlane 


XIElib Events PhotofloDone 


Description 


A PhotofloDone event notifies the client that a photoflo has left the active state. 
It is enabled by the notify argument of XieExecutePhotoflo or 
XieExecuteImmediate. 


The photoflo from which the PhotofloDone event originated is identified by the 
structure fields name space and flo id. The structure field time is the server 
time when the PhotofloDone event occurred, in milliseconds. The reason the 
photoflo left the active state is indicated by the structure field type. 


If the Photoflo terminated because of an error condition, the details concerning 
the error have preceded this event in an error message. 


Structures 


/* PhotofloDone Event Code */ 
#define xieEvnNoPhotofloDone 4 


typedef struct { 
int type; 
unsigned long serial; 
Bool send event; 
Display *display; 
unsigned long name _ space; 
Time time; 
unsigned long flo id; 
} XiePhotofloDoneEvent; 


See Also 


XieExecuteImmediate, XieExecutePhotoflo 


XIElib Errors 


Resource Errors 


The following error codes are allocated from the extension error space to 
provide for the errors returned by XIE: 


Error 
xieErrNoColorlist 


xieErrNoLUT 
xieErrNoPhotoflo 
xieErrNoPhotomap 
xieErrNoPhotospace 
xieErrNoROI 


xieErrNoFlo 


Cause 


The value for a color list argument does not name a 
defined color list. 

The value for a /ut argument does not name a defined 
LUT. 

The value for a photoflo argument does not name a 
defined photoflo. 

The value for a photomap argument does not name a 
defined photomap. 

The value for a photospace argument does not name a 
defined photospace. 

The value for a roi argument does not name a defined 
ROI. 

An error has been detected while defining, executing, or 
accessing a photoflo (see Photoflo Errors). 


XIE also uses the core protocol BadAccess, BadAlloc, BadIDChoice, BadLength, 
BadRequest, and BadValue errors. 


XIElib Errors 


Photoflo Errors 


If an error is detected while defining, executing, or accessing a photoflo, an 
xieErrNoFlo... error is returned. This single error code is allocated from the 
extension error space for all photoflo related errors. The following subcodes are 
defined to provide the details of the error: 


Error 
xieErrNoFloAccess 


xieErrNoFloAlloc 
xieErrNoFloColormap 
xieErrNoFloColorList 
xieErrNoFloDomain 


xieErrNoFloDrawable 
xieErrNoFloElement 


xieErrNoFloGC 
xieErrNoFloID 


xieErrNoFloLength 
xieErrNoFloLUT 
xieErrNoFloMatch 


xieErrNoFloOperator 
xieErrNoFloPhotomap 
xieErrNoFloROI 
xieErrNoFloSource 


xieErrNoFloTechnique 


xieErrNoFloValue 


Cause 


Attempt to execute, modify, or redefine an active 
photoflo or 

attempt to Get/Put client data from/to an inactive 
photoflo. 

Insufficient resources (for example, memory). 
An unknown Colormap has been specified. 
An unknown color list has been specified. 

Invalid domain phototag: 

- source data is not a list-of-rectangles or control-plane 
or 

- specified nonzero on a DIS server. 
An unknown Drawable has been specified. 
An unknown element type has been specified, or 
invalid element type for request, or 

attempt to change or add an element type. 
An unknown GContext has been specified. 

Invalid executable: 

- an unknown photoflo has been specified or 

- an unknown photospace has been specified. 
An element was received with the incorrect number of 
bytes. 
An unknown LUT has been specified. 

Some argument or pair of arguments has the correct 
type and range, but it fails to match in some other way 
required by the element. 
An unknown operator has been specified. 
An unknown photomap has been specified. 
An unknown ROI has been specified. 
An invalid phototag has been specified: 

- zero, but a phototag is required, or 

- downstream from the particular element, or 

- beyond the bounds of the photoflo. 

An unknown technique has been specified , or 

invalid technique specific-parameters have been 
specified, or 

the wrong number of technique-specific parameters 
have been given. 

Some numeric value falls outside of the range of values 
accepted by the element. 


xieErrNoFloImplementation Some aspect of a request is not implemented 
by the server: the client should be prepared to receive 
and handle this error. 


Structures 


/* Definition of Error Codes */ 
#define xieErrNoColorList 
#define xieErrNoLUT 
#define xieErrNoPhotoflo 
#define xieErrNoPhotomap 
#define xieErrNoPhotospace 
#define xieErrNoROI 

#define xieErrNoFlo 


/* Definitions of Flo Error (Sub-) Codes */ 
#define xieErrNoFloAccess 

#define xieErrNoFloAlloc 

#define xieErrNoFloColormap 
#define xieErrNoFloColorList 
#define xieErrNoFloDomain 
#define xieErrNoFloDrawable 
#define xieErrNoFloElement 
#define xieErrNoFloGC 

#define xieErrNoFloID 

#define xieErrNoFloLength 

#define xieErrNoFIloLUT 

#define xieErrNoFloMatch 

#define xieErrNoFloOperator 
#define xieErrNoFloPhotomap 
#define xieErrNoFloROI 

#define xieErrNoFloSource 

#define xieErrNoFloTechnique 
#define xieErrNoFloValue 

#define xieErrNoFloImplementation 


AOurWNrFO 


ODNDUPWNPR 


